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 39 2e 32 2e 20 20 42 ersion 3.9.2. B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20 y combining all
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43 the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65 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 20 0a 2a 2a 20 74 68 not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 . Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 eeded.** if you
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 ng.** language.
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 s file contains
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a tic.#endif./****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e ********** Begin
0560: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e file sqliteInt.
0570: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
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 2a 2f 0a 2f 2a 0a 2a 2a *********/./*.**
05a0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 2001 September
05b0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 15.**.** The aut
05c0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f hor disclaims co
05d0: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 pyright to this
05e0: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e source code. In
05f0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c place of.** a l
0600: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 egal notice, her
0610: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a e is a blessing:
0620: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f .**.** May yo
0630: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f u do good and no
0640: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 t evil..** Ma
0650: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 y you find forgi
0660: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 veness for yours
0670: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 elf and forgive
0680: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 others..** Ma
0690: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 y you share free
06a0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 ly, never taking
06b0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 more than you g
06c0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a ive..**.********
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 2a ****************
0710: 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e *.** Internal in
0720: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 terface definiti
0730: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a ons for SQLite..
0740: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 **.*/.#ifndef _S
0750: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 QLITEINT_H_.#def
0760: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 ine _SQLITEINT_H
0770: 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 _../*.** Include
0780: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
0790: 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 used to customi
07a0: 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 ze the compiler
07b0: 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 options for MSVC
07c0: 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 ..** This should
07d0: 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20 73 be done first s
07e0: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 75 o that it can su
07f0: 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76 65 ccessfully preve
0800: 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 nt spurious.** c
0810: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 ompiler warnings
0820: 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75 65 due to subseque
0830: 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 nt content in th
0840: 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 is file and othe
0850: 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 r files.** that
0860: 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79 20 are included by
0870: 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a this file..*/./*
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e ************* In
0890: 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 clude msvc.h in
08a0: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 the middle of sq
08b0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a liteInt.h ******
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a ************/./*
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 ************* Be
08e0: 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 gin file msvc.h
08f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a ************/./*
0920: 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 79 .** 2015 January
0930: 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 12.**.** The au
0940: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
0950: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
0960: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
0970: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
0980: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
0990: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
09a0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
09b0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
09c0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
09d0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
09e0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
09f0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
0a00: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
0a10: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
0a20: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
0a30: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
0a40: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 *******.**.** Th
0aa0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 is file contains
0ab0: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70 code that is sp
0ac0: 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a ecific to MSVC..
0ad0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56 43 */.#ifndef _MSVC
0ae0: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53 56 _H_.#define _MSV
0af0: 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e 65 C_H_..#if define
0b00: 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72 61 d(_MSC_VER).#pra
0b10: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0b20: 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72 61 ble : 4054).#pra
0b30: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0b40: 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72 61 ble : 4055).#pra
0b50: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0b60: 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72 61 ble : 4100).#pra
0b70: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0b80: 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72 61 ble : 4127).#pra
0b90: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0ba0: 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72 61 ble : 4130).#pra
0bb0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0bc0: 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72 61 ble : 4152).#pra
0bd0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0be0: 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72 61 ble : 4189).#pra
0bf0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0c00: 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72 61 ble : 4206).#pra
0c10: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0c20: 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72 61 ble : 4210).#pra
0c30: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0c40: 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72 61 ble : 4232).#pra
0c50: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0c60: 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72 61 ble : 4244).#pra
0c70: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0c80: 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72 61 ble : 4305).#pra
0c90: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0ca0: 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72 61 ble : 4306).#pra
0cb0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0cc0: 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72 61 ble : 4702).#pra
0cd0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61 gma warning(disa
0ce0: 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e 64 ble : 4706).#end
0cf0: 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 4d if /* defined(_M
0d00: 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e 64 SC_VER) */..#end
0d10: 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 2a if /* _MSVC_H_ *
0d20: 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /../************
0d30: 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68 ** End of msvc.h
0d40: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d70: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
0d80: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 ** Continuing wh
0d90: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 ere we left off
0da0: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a in sqliteInt.h *
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0dc0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 */../*.** Specia
0dd0: 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57 6f l setup for VxWo
0de0: 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a rks.*/./********
0df0: 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 76 ****** Include v
0e00: 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 20 xworks.h in the
0e10: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 middle of sqlite
0e20: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a Int.h **********
0e30: 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a *****/./********
0e40: 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c ****** Begin fil
0e50: 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a e vxworks.h ****
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 *****/./*.** 201
0e90: 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 5-03-02.**.** Th
0ea0: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0eb0: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0ec0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0ed0: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0ee0: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0ef0: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0f00: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0f10: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
0f20: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
0f30: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
0f40: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
0f50: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
0f60: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
0f70: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0f80: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0f90: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0fa0: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a ***********.**.*
1000: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 * This file cont
1010: 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69 ains code that i
1020: 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57 69 s specific to Wi
1030: 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f 72 nd River's VxWor
1040: 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 ks.*/.#if define
1050: 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 65 d(__RTP__) || de
1060: 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e 45 fined(_WRS_KERNE
1070: 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 78 L)./* This is Vx
1080: 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20 74 Works. Set up t
1090: 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 20 hings specially
10a0: 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 for that OS.*/.#
10b0: 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b 73 include <vxWorks
10c0: 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 74 .h>.#include <pt
10d0: 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 hread.h> /* ama
10e0: 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 61 lgamator: dontca
10f0: 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f che */.#define O
1100: 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 66 S_VXWORKS 1.#def
1110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 ine SQLITE_OS_OT
1120: 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53 51 HER 0.#define SQ
1130: 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 LITE_HOMEGROWN_R
1140: 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20 31 ECURSIVE_MUTEX 1
1150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1160: 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 OMIT_LOAD_EXTENS
1170: 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ION 1.#define SQ
1180: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b LITE_ENABLE_LOCK
1190: 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 66 ING_STYLE 0.#def
11a0: 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20 31 ine HAVE_UTIME 1
11b0: 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 69 .#else./* This i
11c0: 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 2a s not VxWorks. *
11d0: 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 57 /.#define OS_VXW
11e0: 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f 2a ORKS 0.#endif /*
11f0: 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 defined(_WRS_KE
1200: 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a RNEL) */../*****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 ********* End of
1220: 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a vxworks.h *****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a ********/./*****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e ********* Contin
1270: 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 uing where we le
1280: 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 ft off in sqlite
1290: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a Int.h **********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a ********/../*.**
12b0: 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 These #defines
12c0: 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 should enable >2
12d0: 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 GB file support
12e0: 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a on POSIX if the.
12f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 ** underlying op
1300: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 erating system s
1310: 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 upports it. If
1320: 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 the OS lacks.**
1330: 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f large file suppo
1340: 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 rt, or if the OS
1350: 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 is windows, the
1360: 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d se should be no-
1370: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 ops..**.** Ticke
1380: 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c t #2739: The _L
1390: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 ARGEFILE_SOURCE
13a0: 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 macro must appea
13b0: 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 r before any.**
13c0: 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 system #includes
13d0: 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 . Hence, this b
13e0: 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 lock of code mus
13f0: 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69 t be the very fi
1400: 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 rst.** code in a
1410: 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e ll source files.
1420: 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c .**.** Large fil
1430: 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 e support can be
1440: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 disabled using
1450: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 the -DSQLITE_DIS
1460: 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a ABLE_LFS switch.
1470: 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ** on the compil
1480: 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e er command line.
1490: 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 This is necess
14a0: 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 ary if you are c
14b0: 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 ompiling.** on a
14c0: 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 recent machine
14d0: 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 (ex: Red Hat 7.2
14e0: 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 ) but you want y
14f0: 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b our code to work
1500: 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 .** on an older
1510: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 machine (ex: Red
1520: 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 Hat 6.0). If y
1530: 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 ou compile on Re
1540: 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 d Hat 7.2.** wit
1550: 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e hout this option
1560: 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e , LFS is enable.
1570: 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e But LFS does n
1580: 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 ot exist in the
1590: 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 kernel.** in Red
15a0: 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 Hat 6.0, so the
15b0: 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b code won't work
15c0: 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 . Hence, for ma
15d0: 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 ximum binary.**
15e0: 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 portability you
15f0: 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e should omit LFS.
1600: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 .**.** The previ
1610: 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61 ous paragraph wa
1620: 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 s written in 200
1630: 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72 5. (This paragr
1640: 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a aph is written.*
1650: 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e * on 2008-11-28.
1660: 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c ) These days, al
1670: 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 l Linux kernels
1680: 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 support large fi
1690: 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 les, so.** you s
16a0: 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c hould probably l
16b0: 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 eave LFS enabled
16c0: 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 . But some embe
16d0: 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d dded platforms m
16e0: 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 ight.** lack LFS
16f0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 in which case t
1700: 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c he SQLITE_DISABL
1710: 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 E_LFS macro migh
1720: 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 t still be usefu
1730: 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 l..**.** Similar
1740: 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 is true for Mac
1750: 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f OS X. LFS is o
1760: 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e nly supported on
1770: 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 Mac OS X 9 and
1780: 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 later..*/.#ifnde
1790: 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 f SQLITE_DISABLE
17a0: 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c _LFS.# define _L
17b0: 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 ARGE_FILE
17c0: 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 1.# ifndef _FILE
17d0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 _OFFSET_BITS.#
17e0: 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 define _FILE_OF
17f0: 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 FSET_BITS 64.# e
1800: 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c ndif.# define _L
1810: 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 ARGEFILE_SOURCE
1820: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68 61 1.#endif../* Wha
1830: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43 43 t version of GCC
1840: 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e 20 is being used.
1850: 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73 20 0 means GCC is
1860: 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20 2a not being used *
1870: 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43 5f /.#ifdef __GNUC_
1880: 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 _.# define GCC_V
1890: 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f 5f ERSION (__GNUC__
18a0: 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 5f *1000000+__GNUC_
18b0: 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f 47 MINOR__*1000+__G
18c0: 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f 5f NUC_PATCHLEVEL__
18d0: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 ).#else.# define
18e0: 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23 GCC_VERSION 0.#
18f0: 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 64 endif../* Needed
1900: 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 66 for various def
1910: 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23 initions... */.#
1920: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 if defined(__GNU
1930: 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 C__) && !defined
1940: 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 20 (_GNU_SOURCE).#
1950: 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 define _GNU_SOUR
1960: 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 64 CE.#endif..#if d
1970: 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44 efined(__OpenBSD
1980: 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 __) && !defined(
1990: 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 64 _BSD_SOURCE).# d
19a0: 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43 efine _BSD_SOURC
19b0: 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 E.#endif../*.**
19c0: 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 6b For MinGW, check
19d0: 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 61 to see if we ca
19e0: 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 65 n include the he
19f0: 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69 ader file contai
1a00: 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 73 ning its.** vers
1a10: 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c ion information,
1a20: 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 among other thi
1a30: 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20 ngs. Normally,
1a40: 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d 69 this internal Mi
1a50: 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 nGW.** header fi
1a60: 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20 le would [only]
1a70: 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 6f be included auto
1a80: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 68 matically by oth
1a90: 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 0a er MinGW header.
1aa0: 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 65 ** files; howeve
1ab0: 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 64 r, the contained
1ac0: 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 version informa
1ad0: 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 75 tion is now requ
1ae0: 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 ired by this.**
1af0: 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 77 header file to w
1b00: 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 72 ork around binar
1b10: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 y compatibility
1b20: 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c 6f issues (see belo
1b30: 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 69 w) and.** this i
1b40: 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e s the only known
1b50: 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c 79 way to reliably
1b60: 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 69 obtain it. Thi
1b70: 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c 6f s entire #if blo
1b80: 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 63 ck.** would be c
1b90: 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 65 ompletely unnece
1ba0: 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20 77 ssary if there w
1bb0: 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 as any other way
1bc0: 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a 2a of detecting.**
1bd0: 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 72 MinGW via their
1be0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 65 preprocessor (e
1bf0: 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 74 .g. if they cust
1c00: 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 43 omized their GCC
1c10: 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 6f to define.** so
1c20: 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 69 me MinGW-specifi
1c30: 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 6e c macros). When
1c40: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 4d compiling for M
1c50: 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 65 inGW, either the
1c60: 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 5f .** _HAVE_MINGW_
1c70: 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e 47 H or _HAVE__MING
1c80: 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 78 W_H (note the ex
1c90: 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 20 tra underscore)
1ca0: 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a 2a macro must be.**
1cb0: 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 77 defined; otherw
1cc0: 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 6f ise, detection o
1cd0: 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 65 f conditions spe
1ce0: 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 77 cific to MinGW w
1cf0: 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 6c ill be.** disabl
1d00: 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e ed..*/.#if defin
1d10: 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48 ed(_HAVE_MINGW_H
1d20: 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 6e ).# include "min
1d30: 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 69 gw.h".#elif defi
1d40: 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 ned(_HAVE__MINGW
1d50: 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 5f _H).# include "_
1d60: 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 0a mingw.h".#endif.
1d70: 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 ./*.** For MinGW
1d80: 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 6e version 4.x (an
1d90: 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 6b d higher), check
1da0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 5f to see if the _
1db0: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 USE_32BIT_TIME_T
1dc0: 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 65 .** define is re
1dd0: 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 61 quired to mainta
1de0: 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 in binary compat
1df0: 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65 ibility with the
1e00: 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a 2a MSVC runtime.**
1e10: 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20 library in use
1e20: 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f 77 (e.g. for Window
1e30: 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 64 s XP)..*/.#if !d
1e40: 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 49 efined(_USE_32BI
1e50: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 65 T_TIME_T) && !de
1e60: 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 54 fined(_USE_64BIT
1e70: 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 20 _TIME_T) && \.
1e80: 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32 defined(_WIN32
1e90: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 57 ) && !defined(_W
1ea0: 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 64 IN64) && \. d
1eb0: 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d efined(__MINGW_M
1ec0: 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 26 AJOR_VERSION) &&
1ed0: 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 __MINGW_MAJOR_V
1ee0: 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 5c ERSION >= 4 && \
1ef0: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d . defined(__M
1f00: 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 6e SVCRT__).# defin
1f10: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d e _USE_32BIT_TIM
1f20: 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 E_T.#endif../* T
1f30: 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 65 he public SQLite
1f40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 interface. The
1f50: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 _FILE_OFFSET_BI
1f60: 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 TS macro must ap
1f70: 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 6e pear.** first in
1f80: 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 65 QNX. Also, the
1f90: 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 _USE_32BIT_TIME
1fa0: 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 _T macro must ap
1fb0: 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a 2a pear first for.*
1fc0: 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a * MinGW..*/./***
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c *********** Incl
1fe0: 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e ude sqlite3.h in
1ff0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 the middle of s
2000: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a qliteInt.h *****
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a **********/./***
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 *********** Begi
2030: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 n file sqlite3.h
2040: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a **********/./*.*
2070: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 * 2001 September
2080: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 15.**.** The au
2090: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
20a0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
20b0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
20c0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
20d0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
20e0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
20f0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
2100: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
2110: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
2120: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
2130: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
2140: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
2150: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
2160: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
2170: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
2180: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
2190: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 **.** This heade
21f0: 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 r file defines t
2200: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 he interface tha
2210: 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 t the SQLite lib
2220: 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 rary.** presents
2230: 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 to client progr
2240: 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e ams. If a C-fun
2250: 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 ction, structure
2260: 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f , datatype,.** o
2270: 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e r constant defin
2280: 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 ition does not a
2290: 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 ppear in this fi
22a0: 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a le, then it is.*
22b0: 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 * not a publishe
22c0: 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c d API of SQLite,
22d0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
22e0: 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a hange without.**
22f0: 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f notice, and sho
2300: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 uld not be refer
2310: 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d enced by program
2320: 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 s that use SQLit
2330: 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 e..**.** Some of
2340: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 the definitions
2350: 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 that are in thi
2360: 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 s file are marke
2370: 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d d as.** "experim
2380: 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d ental". Experim
2390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
23a0: 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 are normally ne
23b0: 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 w.** features re
23c0: 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 cently added to
23d0: 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e SQLite. We do n
23e0: 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 ot anticipate ch
23f0: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 anges.** to expe
2400: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 rimental interfa
2410: 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 ces but reserve
2420: 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b the right to mak
2430: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a e minor changes.
2440: 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 ** if experience
2450: 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 from use "in th
2460: 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 e wild" suggest
2470: 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 such changes are
2480: 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 prudent..**.**
2490: 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c The official C-l
24a0: 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 anguage API docu
24b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 mentation for SQ
24c0: 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a Lite is derived.
24d0: 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 ** from comments
24e0: 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 in this file.
24f0: 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 This file is the
2500: 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 authoritative s
2510: 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 ource.** on how
2520: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
2530: 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 74 s are supposed t
2540: 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a o operate..**.**
2550: 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 The name of thi
2560: 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e s file under con
2570: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 figuration manag
2580: 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 ement is "sqlite
2590: 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d .h.in"..** The m
25a0: 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f akefile makes so
25b0: 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 me minor changes
25c0: 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 to this file (s
25d0: 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 uch as inserting
25e0: 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 .** the version
25f0: 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e number) and chan
2600: 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 ges its name to
2610: 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a "sqlite3.h" as.*
2620: 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 * part of the bu
2630: 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a ild process..*/.
2640: 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 #ifndef _SQLITE3
2650: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c _H_.#define _SQL
2660: 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 ITE3_H_.#include
2670: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 <stdarg.h>
2680: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 /* Needed for th
2690: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 e definition of
26a0: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a va_list */../*.*
26b0: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 * Make sure we c
26c0: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 an call this stu
26d0: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a ff from C++..*/.
26e0: 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 #if 0.extern "C"
26f0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
2700: 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 62 * Provide the ab
2710: 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64 ility to overrid
2720: 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72 e linkage featur
2730: 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 es of the interf
2740: 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ace..*/.#ifndef
2750: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 SQLITE_EXTERN.#
2760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 define SQLITE_EX
2770: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 TERN extern.#end
2780: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
2790: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 E_API.# define S
27a0: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 QLITE_API.#endif
27b0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
27c0: 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 CDECL.# define S
27d0: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 QLITE_CDECL.#end
27e0: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
27f0: 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69 E_STDCALL.# defi
2800: 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c ne SQLITE_STDCAL
2810: 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 L.#endif../*.**
2820: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 These no-op macr
2830: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 os are used in f
2840: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 ront of interfac
2850: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 es to mark those
2860: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
2870: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61 s either depreca
2880: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e ted or experimen
2890: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 tal. New applic
28a0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
28b0: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 not use depreca
28c0: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d ted interfaces -
28d0: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 they are suppor
28e0: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ted for backward
28f0: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 s.** compatibili
2900: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 ty only. Applic
2910: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 ation writers sh
2920: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 ould be aware th
2930: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 at.** experiment
2940: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
2950: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 e subject to cha
2960: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c nge in point rel
2970: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eases..**.** The
2980: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 se macros used t
2990: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 o resolve to var
29a0: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f ious kinds of co
29b0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 mpiler magic tha
29c0: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 t.** would gener
29d0: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 ate warning mess
29e0: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 ages when they w
29f0: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 ere used. But t
2a00: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 hat.** compiler
2a10: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 magic ended up g
2a20: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 enerating such a
2a30: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 flurry of bug r
2a40: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 eports.** that w
2a50: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 e have taken it
2a60: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 all out and gone
2a70: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 back to using s
2a80: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 imple.** noop ma
2a90: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 cros..*/.#define
2aa0: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
2ab0: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 ED.#define SQLIT
2ac0: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a E_EXPERIMENTAL..
2ad0: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 /*.** Ensure the
2ae0: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 se symbols were
2af0: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 not defined by s
2b00: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 ome previous hea
2b10: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 der file..*/.#if
2b20: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
2b30: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 ON.# undef SQLIT
2b40: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 E_VERSION.#endif
2b50: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
2b60: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 ERSION_NUMBER.#
2b70: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
2b80: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 SION_NUMBER.#end
2b90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
2ba0: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
2bb0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
2bc0: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e Numbers.**.** ^
2bd0: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 (The [SQLITE_VER
2be0: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 SION] C preproce
2bf0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 ssor macro in th
2c00: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 e sqlite3.h head
2c10: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 er.** evaluates
2c20: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
2c30: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 ral that is the
2c40: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 SQLite version i
2c50: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 n the.** format
2c60: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 "X.Y.Z" where X
2c70: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 is the major ver
2c80: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 sion number (alw
2c90: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c ays 3 for.** SQL
2ca0: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 ite3) and Y is t
2cb0: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e he minor version
2cc0: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 number and Z is
2cd0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d the release num
2ce0: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 ber.)^.** ^(The
2cf0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
2d00: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f NUMBER] C prepro
2d10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 cessor macro res
2d20: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 olves to an inte
2d30: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ger.** with the
2d40: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 value (X*1000000
2d50: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 + Y*1000 + Z) w
2d60: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a here X, Y, and Z
2d70: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a are the same.**
2d80: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e numbers used in
2d90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
2da0: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ].)^.** The SQLI
2db0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
2dc0: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 R for any given
2dd0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
2de0: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 e will also.** b
2df0: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 e larger than th
2e00: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 e release from w
2e10: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 hich it is deriv
2e20: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 ed. Either Y wi
2e30: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f ll.** be held co
2e40: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c nstant and Z wil
2e50: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 l be incremented
2e60: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 or else Y will
2e70: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a be incremented.*
2e80: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 * and Z will be
2e90: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a reset to zero..*
2ea0: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 *.** Since versi
2eb0: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 on 3.6.18, SQLit
2ec0: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 e source code ha
2ed0: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e s been stored in
2ee0: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
2ef0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 "http://www.foss
2f00: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 il-scm.org/">Fos
2f10: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f sil configuratio
2f20: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 n management.**
2f30: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 system</a>. ^Th
2f40: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
2f50: 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 ID macro evaluat
2f60: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e es to.** a strin
2f70: 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 g which identifi
2f80: 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 es a particular
2f90: 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 check-in of SQLi
2fa0: 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 te.** within its
2fb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
2fc0: 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d anagement system
2fd0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 . ^The SQLITE_S
2fe0: 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 OURCE_ID.** stri
2ff0: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ng contains the
3000: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 date and time of
3010: 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 the check-in (U
3020: 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a TC) and an SHA1.
3030: 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 ** hash of the e
3040: 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 ntire source tre
3050: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3060: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
3070: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
3080: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
3090: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
30a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
30b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
30c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
30d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
30e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
30f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
3100: 20 20 20 20 22 33 2e 39 2e 32 22 0a 23 64 65 66 "3.9.2".#def
3110: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
3120: 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 39 30 30 ON_NUMBER 300900
3130: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
3140: 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 _SOURCE_ID
3150: 22 32 30 31 35 2d 31 31 2d 30 32 20 31 38 3a 33 "2015-11-02 18:3
3160: 31 3a 34 35 20 62 64 61 37 37 64 64 61 39 36 39 1:45 bda77dda969
3170: 37 63 34 36 33 63 33 64 30 37 30 34 30 31 34 64 7c463c3d0704014d
3180: 35 31 36 32 37 66 63 65 65 65 33 32 38 22 0a 0a 51627fceee328"..
3190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31a0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 Run-Time Library
31b0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 Version Numbers
31c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
31d0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 lite3_version, s
31e0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a qlite3_sourceid.
31f0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
3200: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 rfaces provide t
3210: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
3220: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 ion as the [SQLI
3230: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 TE_VERSION],.**
3240: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
3250: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 NUMBER], and [SQ
3260: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
3270: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
3280: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 acros.** but are
3290: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
32a0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 the library ins
32b0: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 tead of the head
32c0: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 er file. ^(Caut
32d0: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d ious.** programm
32e0: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 ers might includ
32f0: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 e assert() state
3300: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 ments in their a
3310: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a pplication to.**
3320: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c verify that val
3330: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
3340: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
3350: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f match the macro
3360: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 s in.** the head
3370: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 er, and thus ens
3380: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 ure that the app
3390: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 lication is.** c
33a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 ompiled with mat
33b0: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e ching library an
33c0: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a d header files..
33d0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
33e0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 e><pre>.** asser
33f0: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 t( sqlite3_libve
3400: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d rsion_number()==
3410: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
3420: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 UMBER );.** asse
3430: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 rt( strcmp(sqlit
3440: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 e3_sourceid(),SQ
3450: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d LITE_SOURCE_ID)=
3460: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 =0 );.** assert(
3470: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f strcmp(sqlite3_
3480: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c libversion(),SQL
3490: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 ITE_VERSION)==0
34a0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
34b0: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
34c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
34d0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 ersion[] string
34e0: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e constant contain
34f0: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 s the text of [S
3500: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a QLITE_VERSION].*
3510: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 * macro. ^The s
3520: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
3530: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
3540: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
3550: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 o the.** to the
3560: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
3570: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
3580: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
3590: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 libversion().**
35a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 function is prov
35b0: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 ided for use in
35c0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 DLLs since DLL u
35d0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 sers usually do
35e0: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 not have.** dire
35f0: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 ct access to str
3600: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 ing constants wi
3610: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e thin the DLL. ^
3620: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c The.** sqlite3_l
3630: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
3640: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
3650: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 rns an integer e
3660: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 qual to.** [SQLI
3670: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
3680: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 R]. ^The sqlite
3690: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 3_sourceid() fun
36a0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a ction returns .*
36b0: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
36c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
36d0: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 whose value is
36e0: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
36f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 .** [SQLITE_SOUR
3700: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 CE_ID] C preproc
3710: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a essor macro..**.
3720: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
3730: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 lite_version()]
3740: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 and [sqlite_sour
3750: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c ce_id()]..*/.SQL
3760: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
3770: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
3780: 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 on[] = SQLITE_VE
3790: 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 RSION;.SQLITE_AP
37a0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
37b0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
37c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
37d0: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
37e0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
37f0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
3800: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f ite3_sourceid(vo
3810: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
3820: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
3830: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 LL sqlite3_libve
3840: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 rsion_number(voi
3850: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
3860: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
3870: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f brary Compilatio
3880: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f n Options Diagno
3890: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 stics.**.** ^The
38a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
38b0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 option_used() fu
38c0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 nction returns 0
38d0: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 or 1 .** indica
38e0: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 ting whether the
38f0: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f specified optio
3900: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 n was defined at
3910: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d .** compile tim
3920: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f e. ^The SQLITE_
3930: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f prefix may be o
3940: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
3950: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 .** option name
3960: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 passed to sqlite
3970: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
3980: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 used(). .**.**
3990: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d ^The sqlite3_com
39a0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
39b0: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 function allows
39c0: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 iterating.** ov
39d0: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f er the list of o
39e0: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 ptions that were
39f0: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 defined at comp
3a00: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 ile time by.** r
3a10: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 eturning the N-t
3a20: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f h compile time o
3a30: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e ption string. ^
3a40: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 If N is out of r
3a50: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 ange,.** sqlite3
3a60: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
3a70: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e et() returns a N
3a80: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 ULL pointer. ^T
3a90: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 he SQLITE_ .** p
3aa0: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 refix is omitted
3ab0: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 from any string
3ac0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a s returned by .*
3ad0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c * sqlite3_compil
3ae0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a eoption_get()..*
3af0: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f *.** ^Support fo
3b00: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 r the diagnostic
3b10: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 functions sqlit
3b20: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3b30: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 _used().** and s
3b40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
3b50: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 tion_get() may b
3b60: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 e omitted by spe
3b70: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 cifying the .**
3b80: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d [SQLITE_OMIT_COM
3b90: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 PILEOPTION_DIAGS
3ba0: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 ] option at comp
3bb0: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ile time..**.**
3bc0: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 See also: SQL fu
3bd0: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f nctions [sqlite_
3be0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
3bf0: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
3c00: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 lite_compileopti
3c10: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 on_get()] and th
3c20: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f e [compile_optio
3c30: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 ns pragma]..*/.#
3c40: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d ifndef SQLITE_OM
3c50: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
3c60: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 _DIAGS.SQLITE_AP
3c70: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
3c80: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d CALL sqlite3_com
3c90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
3ca0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 const char *zOpt
3cb0: 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Name);.SQLITE_AP
3cc0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
3cd0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
3ce0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
3cf0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 on_get(int N);.#
3d00: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
3d10: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
3d20: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
3d30: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a y Is Threadsafe.
3d40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3d50: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
3d60: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
3d70: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c zero if and onl
3d80: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 y if.** SQLite w
3d90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
3da0: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
3db0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 mitted due to th
3dc0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
3dd0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 EADSAFE] compile
3de0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 -time option bei
3df0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a ng set to 0..**.
3e00: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 ** SQLite can be
3e10: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f compiled with o
3e20: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 r without mutexe
3e30: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 s. When.** the
3e40: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
3e50: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 FE] C preprocess
3e60: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 or macro is 1 or
3e70: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 2, mutexes.** a
3e80: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 re enabled and S
3e90: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 QLite is threads
3ea0: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a afe. When the.*
3eb0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
3ec0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 SAFE] macro is 0
3ed0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 , .** the mutexe
3ee0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 s are omitted.
3ef0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 Without the mute
3f00: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 xes, it is not s
3f10: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 afe.** to use SQ
3f20: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c Lite concurrentl
3f30: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e y from more than
3f40: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a one thread..**.
3f50: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 ** Enabling mute
3f60: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 xes incurs a mea
3f70: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 surable performa
3f80: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 nce penalty..**
3f90: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f So if speed is o
3fa0: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 f utmost importa
3fb0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 nce, it makes se
3fc0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a nse to disable.*
3fd0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 * the mutexes.
3fe0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 But for maximum
3ff0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 safety, mutexes
4000: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 should be enable
4010: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 d..** ^The defau
4020: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 lt behavior is f
4030: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 or mutexes to be
4040: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
4050: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
4060: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e an be used by an
4070: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
4080: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
4090: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 he.** version of
40a0: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 SQLite that it
40b0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e is linking again
40c0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 st was compiled
40d0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 with.** the desi
40e0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 red setting of t
40f0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
4100: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a DSAFE] macro..**
4110: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
4120: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 ce only reports
4130: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 on the compile-t
4140: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e ime mutex settin
4150: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c g.** of the [SQL
4160: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
4170: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 flag. If SQLite
4180: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
4190: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 h.** SQLITE_THRE
41a0: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 ADSAFE=1 or =2 t
41b0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
41c0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
41d0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
41e0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
41f0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
4200: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
4210: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
4220: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
4230: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
4240: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
4250: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
4260: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
4270: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
4280: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 G_SERIALIZED].
4290: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c ^(The return val
42a0: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c ue of the.** sql
42b0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
42c0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 ) function shows
42d0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c only the compil
42e0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f e-time setting o
42f0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 f.** thread safe
4300: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d ty, not any run-
4310: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 time changes to
4320: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 that setting mad
4330: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f e by.** sqlite3_
4340: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 config(). In oth
4350: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 er words, the re
4360: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
4370: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
4380: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 fe().** is uncha
4390: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f nged by calls to
43a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
43b0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 ).)^.**.** See t
43c0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
43d0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
43e0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
43f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
4400: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
4410: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
4420: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
4430: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 e(void);../*.**
4440: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
4450: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 se Connection Ha
4460: 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ndle.** KEYWORDS
4470: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e : {database conn
4480: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 ection} {databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a e connections}.*
44a0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 *.** Each open S
44b0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 QLite database i
44c0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
44d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
44e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 instance of.**
44f0: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 the opaque struc
4500: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 ture named "sqli
4510: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 te3". It is use
4520: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 ful to think of
4530: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f an sqlite3.** po
4540: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 inter as an obje
4550: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ct. The [sqlite
4560: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
4570: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 te3_open16()], a
4580: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f nd.** [sqlite3_o
4590: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
45a0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e aces are its con
45b0: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b structors, and [
45c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
45d0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
45e0: 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 _close_v2()] are
45f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 its destructors
4600: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e . There are man
4610: 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 y other.** inter
4620: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a faces (such as.*
4630: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
4640: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 re_v2()], [sqlit
4650: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
4660: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 on()], and.** [s
4670: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
4680: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 out()] to name b
4690: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 ut three) that a
46a0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e re methods on an
46b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 .** sqlite3 obje
46c0: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ct..*/.typedef s
46d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 truct sqlite3 sq
46e0: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lite3;../*.** CA
46f0: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 PI3REF: 64-Bit I
4700: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 nteger Types.**
4710: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
4720: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
4730: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
4740: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
4750: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
4760: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
4770: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
4780: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
4790: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
47a0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
47b0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
47c0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
47d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
47e0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
47f0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
4800: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
4810: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
4820: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
4830: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
4840: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
4850: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
4860: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
4870: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nly..**.** ^The
4880: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
4890: 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 d sqlite_int64 t
48a0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 ypes can store i
48b0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a nteger values.**
48c0: 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 between -922337
48d0: 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 2036854775808 an
48e0: 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 d +9223372036854
48f0: 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 775807 inclusive
4900: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
4910: 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 e3_uint64 and sq
4920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
4930: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 s can store inte
4940: 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 ger values .** b
4950: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 etween 0 and +18
4960: 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 4467440737095516
4970: 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 15 inclusive..*/
4980: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
4990: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
49a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
49b0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
49c0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
49d0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
49e0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
49f0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
4a00: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
4a10: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
4a20: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
4a30: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
4a40: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
4a50: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
4a60: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
4a70: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
4a80: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
4a90: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
4aa0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
4ab0: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
4ac0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
4ad0: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
4ae0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
4af0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
4b00: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
4b10: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
4b20: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
4b30: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
4b40: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
4b50: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
4b60: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
4b70: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
4b80: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
4b90: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
4ba0: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
4bb0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
4bc0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
4bd0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
4be0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
4bf0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
4c00: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 onnection.** DES
4c10: 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 TRUCTOR: sqlite3
4c20: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
4c30: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
4c40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
4c50: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
4c60: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 destructors.** f
4c70: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d or the [sqlite3]
4c80: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c object..** ^Cal
4c90: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c ls to sqlite3_cl
4ca0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
4cb0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 3_close_v2() ret
4cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
4cd0: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 if.** the [sqlit
4ce0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 e3] object is su
4cf0: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 ccessfully destr
4d00: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 oyed and all ass
4d10: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 ociated.** resou
4d20: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 rces are dealloc
4d30: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ated..**.** ^If
4d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
4d50: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 nection is assoc
4d60: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e iated with unfin
4d70: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a alized prepared.
4d80: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 ** statements or
4d90: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 unfinished sqli
4da0: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 te3_backup objec
4db0: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ts then sqlite3_
4dc0: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 close().** will
4dd0: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 leave the databa
4de0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
4df0: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 en and return [S
4e00: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 QLITE_BUSY]..**
4e10: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ^If sqlite3_clos
4e20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 e_v2() is called
4e30: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
4e40: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 d prepared state
4e50: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 ments.** and/or
4e60: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 unfinished sqlit
4e70: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e e3_backups, then
4e80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
4e90: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 nnection becomes
4ea0: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 .** an unusable
4eb0: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 "zombie" which w
4ec0: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
4ed0: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 y be deallocated
4ee0: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 when the.** las
4ef0: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 t prepared state
4f00: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 ment is finalize
4f10: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 d or the last sq
4f20: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a lite3_backup is.
4f30: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 ** finished. Th
4f40: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f e sqlite3_close_
4f50: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 v2() interface i
4f60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 s intended for u
4f70: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 se with.** host
4f80: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 languages that a
4f90: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 re garbage colle
4fa0: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 cted, and where
4fb0: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 the order in whi
4fc0: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 ch.** destructor
4fd0: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 s are called is
4fe0: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a arbitrary..**.**
4ff0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
5000: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ould [sqlite3_fi
5010: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
5020: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 e] all [prepared
5030: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a statements],.**
5040: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
5050: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c lose | close] al
5060: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d l [BLOB handles]
5070: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 , and .** [sqlit
5080: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
5090: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b | finish] all [
50a0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
50b0: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 objects associat
50c0: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b ed.** with the [
50d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
50e0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
50f0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
5100: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
5110: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
5120: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 2() is called on
5130: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
5140: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 nection] that st
5150: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 ill has.** outst
5160: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 anding [prepared
5170: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 statements], [B
5180: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e LOB handles], an
5190: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d/or.** [sqlite3
51a0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
51b0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 then it returns
51c0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 [SQLITE_OK] and
51d0: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f the deallocatio
51e0: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 n.** of resource
51f0: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e s is deferred un
5200: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 til all [prepare
5210: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b d statements], [
5220: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a BLOB handles],.*
5230: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 * and [sqlite3_b
5240: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 ackup] objects a
5250: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 re also destroye
5260: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
5270: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
5280: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 is destroyed wh
5290: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
52a0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
52b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
52c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
52d0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
52e0: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
52f0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
5300: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c ose(C)] and [sql
5310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 ite3_close_v2(C)
5320: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
5330: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
5340: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
5350: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
5360: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
5370: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
5380: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
5390: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
53a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
53b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
53c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
53d0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 ..** ^Calling sq
53e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 lite3_close() or
53f0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
5400: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 2() with a NULL
5410: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d pointer.** argum
5420: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ent is a harmles
5430: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 s no-op..*/.SQLI
5440: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
5450: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
5460: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
5470: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
5480: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
5490: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
54a0: 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 2(sqlite3*);../*
54b0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 .** The type for
54c0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
54d0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 tion..** This is
54e0: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 legacy and depr
54f0: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 ecated. It is i
5500: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 ncluded for hist
5510: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 orical.** compat
5520: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e ibility and is n
5530: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a ot documented..*
5540: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a /.typedef int (*
5550: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b sqlite3_callback
5560: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
5570: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a **, char**);../*
5580: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
5590: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 e-Step Query Exe
55a0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 cution Interface
55b0: 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
55c0: 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te3.**.** The sq
55d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
55e0: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 erface is a conv
55f0: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 enience wrapper
5600: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
5610: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
5620: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
5630: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
5640: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a _finalize()],.**
5650: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 that allows an
5660: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 application to r
5670: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 un multiple stat
5680: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a ements of SQL.**
5690: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 without having
56a0: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 to use a lot of
56b0: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e C code. .**.** ^
56c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
56d0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e () interface run
56e0: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 s zero or more U
56f0: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a TF-8 encoded,.**
5700: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 semicolon-separ
5710: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ate SQL statemen
5720: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 ts passed into i
5730: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c ts 2nd argument,
5740: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 .** in the conte
5750: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 xt of the [datab
5760: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
5770: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 passed in as its
5780: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 1st.** argument
5790: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 . ^If the callb
57a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 ack function of
57b0: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 the 3rd argument
57c0: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 to.** sqlite3_e
57d0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
57e0: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e L, then it is in
57f0: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 voked for each r
5800: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d esult row.** com
5810: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 ing out of the e
5820: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 valuated SQL sta
5830: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 tements. ^The 4
5840: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a th argument to.*
5850: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
5860: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f is relayed thro
5870: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 ugh to the 1st a
5880: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a rgument of each.
5890: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f ** callback invo
58a0: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 cation. ^If the
58b0: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 callback pointe
58c0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
58d0: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 c().** is NULL,
58e0: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b then no callback
58f0: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 is ever invoked
5900: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 and result rows
5910: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e are.** ignored.
5920: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 .**.** ^If an er
5930: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 ror occurs while
5940: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 evaluating the
5950: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
5960: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 assed into.** sq
5970: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 lite3_exec(), th
5980: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 en execution of
5990: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
59a0: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a ement stops and.
59b0: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 ** subsequent st
59c0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 atements are ski
59d0: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 pped. ^If the 5
59e0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
59f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
5a00: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 * is not NULL th
5a10: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 en any error mes
5a20: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 sage is written
5a30: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
5a40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
5a50: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
5a60: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 and passed back
5a70: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
5a80: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f parameter..** To
5a90: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 avoid memory le
5aa0: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 aks, the applica
5ab0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f tion should invo
5ac0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ke [sqlite3_free
5ad0: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 ()].** on error
5ae0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 message strings
5af0: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 returned through
5b00: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
5b10: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 er of.** of sqli
5b20: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 te3_exec() after
5b30: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
5b40: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 ge string is no
5b50: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a longer needed..*
5b60: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 * ^If the 5th pa
5b70: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
5b80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 e3_exec() is not
5b90: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 NULL and no err
5ba0: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 ors.** occur, th
5bb0: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 en sqlite3_exec(
5bc0: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 ) sets the point
5bd0: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 er in its 5th pa
5be0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 rameter to.** NU
5bf0: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e LL before return
5c00: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 ing..**.** ^If a
5c10: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
5c20: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
5c30: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
5c40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
5c50: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
5c60: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 s SQLITE_ABORT w
5c70: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 ithout invoking
5c80: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 the callback aga
5c90: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 in and.** withou
5ca0: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 t running any su
5cb0: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 bsequent SQL sta
5cc0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
5cd0: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 The 2nd argument
5ce0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
5cf0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
5d00: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a function is the.
5d10: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c ** number of col
5d20: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
5d30: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 lt. ^The 3rd ar
5d40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
5d50: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
5d60: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
5d70: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
5d80: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 to strings obta
5d90: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a ined as if from.
5da0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
5db0: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 mn_text()], one
5dc0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e for each column.
5dd0: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 ^If an element
5de0: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 of a.** result
5df0: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e row is NULL then
5e00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
5e10: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ng string pointe
5e20: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c r for the.** sql
5e30: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c ite3_exec() call
5e40: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 back is a NULL p
5e50: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 ointer. ^The 4t
5e60: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 h argument to th
5e70: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 e.** sqlite3_exe
5e80: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 c() callback is
5e90: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
5ea0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
5eb0: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e where each.** en
5ec0: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 try represents t
5ed0: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 he name of corre
5ee0: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 sponding result
5ef0: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e column as obtain
5f00: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
5f10: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
5f20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 )]..**.** ^If th
5f30: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
5f40: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
5f50: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
5f60: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a ter, a pointer.*
5f70: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 * to an empty st
5f80: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 ring, or a point
5f90: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 er that contains
5fa0: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 only whitespace
5fb0: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 and/or .** SQL
5fc0: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e comments, then n
5fd0: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
5fe0: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 are evaluated a
5ff0: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a nd the database.
6000: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 ** is not change
6010: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 d..**.** Restric
6020: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c tions:.**.** <ul
6030: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 >.** <li> The ap
6040: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 plication must e
6050: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 nsure that the 1
6060: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
6070: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
6080: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 * is a vali
6090: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 d and open [data
60a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
60b0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
60c0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
60d0: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 ot close the [da
60e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
60f0: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a n] specified by.
6100: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 ** the 1st
6110: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
6120: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c ite3_exec() whil
6130: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
6140: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
6150: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 <li> The applica
6160: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f tion must not mo
6170: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 dify the SQL sta
6180: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 tement text pass
6190: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 ed into.**
61a0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
61b0: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 r of sqlite3_exe
61c0: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 c() while sqlite
61d0: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 3_exec() is runn
61e0: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f ing..** </ul>.*/
61f0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
6200: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
6210: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
6220: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6240: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
6250: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
6260: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
6270: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
6290: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
62a0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
62b0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
62c0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
62d0: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
62e0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
62f0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6310: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
6320: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
6330: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
6340: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6360: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
6370: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
6380: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
6390: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
63a0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
63b0: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 {result code de
63c0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
63d0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
63e0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
63f0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
6400: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
6410: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
6420: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
6430: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 cate success or
6440: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e failure..**.** N
6450: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d ew error codes m
6460: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
6470: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
6480: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
6490: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e See also: [exten
64a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ded result code
64b0: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a definitions].*/.
64c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
64d0: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 K 0
64e0: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 /* Successful re
64f0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e sult */./* begin
6500: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f ning-of-error-co
6510: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 des */.#define S
6520: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 QLITE_ERROR
6530: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 1 /* SQL er
6540: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 ror or missing d
6550: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
6560: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e ne SQLITE_INTERN
6570: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e AL 2 /* In
6580: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 ternal logic err
6590: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a or in SQLite */.
65a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
65b0: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 ERM 3
65c0: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 /* Access permis
65d0: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 sion denied */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 define SQLITE_AB
65f0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f ORT 4 /
6600: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 * Callback routi
6610: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 ne requested an
6620: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 abort */.#define
6630: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 SQLITE_BUSY
6640: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 5 /* The
6650: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
6660: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
6670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 ne SQLITE_LOCKED
6680: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 6 /* A
6690: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 table in the dat
66a0: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 abase is locked
66b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
66c0: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 E_NOMEM 7
66d0: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 /* A malloc()
66e0: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 failed */.#defi
66f0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
6700: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 LY 8 /* At
6710: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 tempt to write a
6720: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 readonly databa
6730: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
6740: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 LITE_INTERRUPT
6750: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 9 /* Operati
6760: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 on terminated by
6770: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
6780: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pt()*/.#define S
6790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 QLITE_IOERR
67a0: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 10 /* Some k
67b0: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 ind of disk I/O
67c0: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a error occurred *
67d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
67e0: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 _CORRUPT 11
67f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
6800: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 e disk image is
6810: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 malformed */.#de
6820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 fine SQLITE_NOTF
6830: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 OUND 12 /*
6840: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 Unknown opcode i
6850: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 n sqlite3_file_c
6860: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 ontrol() */.#def
6870: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
6880: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
6890: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
68a0: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
68b0: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
68d0: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
68e0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
68f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
6900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6910: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
6920: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c /* Database l
6930: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
6940: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
6950: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
6960: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
6970: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
6980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
6990: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
69a0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
69b0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
69c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
69d0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
69e0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
69f0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
6a00: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
6a10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
6a20: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
6a30: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
6a40: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
6a60: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
6a70: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
6a80: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
6a90: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
6aa0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
6ab0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
6ac0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
6ad0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
6ae0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
6af0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
6b00: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
6b10: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
6b20: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
6b30: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
6b40: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
6b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
6b60: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
6b70: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
6b80: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
6b90: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
6ba0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
6bb0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
6bc0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
6bd0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
6be0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
6bf0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
6c00: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
6c10: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
6c20: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
6c30: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
6c40: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 ITE_NOTICE
6c50: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 27 /* Notifica
6c60: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 tions from sqlit
6c70: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 e3_log() */.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
6c90: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 NG 28 /* W
6ca0: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c arnings from sql
6cb0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 efine SQLITE_ROW
6cd0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 100 /*
6ce0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
6cf0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 has another row
6d00: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ready */.#define
6d10: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 SQLITE_DONE
6d20: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 101 /* sqli
6d30: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 te3_step() has f
6d40: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
6d50: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 g */./* end-of-e
6d60: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f rror-codes */../
6d70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
6d80: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
6d90: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
6da0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 : {extended resu
6db0: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
6dc0: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 ons}.**.** In it
6dd0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
6de0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
6df0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
6e00: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e urn one of 30 in
6e10: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 teger.** [result
6e20: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
6e30: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
6e40: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
6e50: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
6e60: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
6e70: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
6e80: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
6e90: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
6ea0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
6eb0: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
6ec0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
6ed0: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
6ee0: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
6ef0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
6f00: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
6f10: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
6f20: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e .8 and later) in
6f30: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 clude.** support
6f40: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
6f50: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 result codes tha
6f60: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 t provide more d
6f70: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 etailed informat
6f80: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 ion.** about err
6f90: 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 ors. These [exte
6fa0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
6fb0: 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f s] are enabled o
6fc0: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e r disabled.** on
6fd0: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 a per database
6fe0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
6ff0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
7000: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
7010: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 result_codes()]
7020: 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 API. Or, the ex
7030: 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a tended code for.
7040: 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ** the most rece
7050: 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 nt error can be
7060: 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a obtained using.*
7070: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
7080: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a ded_errcode()]..
7090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
70a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 E_IOERR_READ
70b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
70c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 E_IOERR | (1<<8)
70d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
70e0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
70f0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
7100: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 _IOERR | (2<<8))
7110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7120: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 IOERR_WRITE
7130: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
7140: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a IOERR | (3<<8)).
7150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7160: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 OERR_FSYNC
7170: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7180: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 OERR | (4<<8)).#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
71a0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 ERR_DIR_FSYNC
71b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
71c0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 ERR | (5<<8)).#d
71d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
71e0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 RR_TRUNCATE
71f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
7200: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 RR | (6<<8)).#de
7210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7220: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 R_FSTAT
7230: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7240: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 R | (7<<8)).#def
7250: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7260: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 _UNLOCK
7270: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7280: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (8<<8)).#defi
7290: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
72a0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 RDLOCK
72b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
72c0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
72d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
72e0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
72f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7300: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (10<<8)).#defin
7310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 e SQLITE_IOERR_B
7320: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 LOCKED
7330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7340: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (11<<8)).#defin
7350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e e SQLITE_IOERR_N
7360: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 OMEM
7370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7380: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (12<<8)).#defin
7390: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 e SQLITE_IOERR_A
73a0: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 CCESS
73b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
73c0: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (13<<8)).#defin
73d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
73e0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b HECKRESERVEDLOCK
73f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7400: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (14<<8)).#defin
7410: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c e SQLITE_IOERR_L
7420: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 OCK
7430: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7440: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (15<<8)).#defin
7450: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
7460: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 LOSE
7470: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7480: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (16<<8)).#defin
7490: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
74a0: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 IR_CLOSE
74b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
74c0: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e (17<<8)).#defin
74d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
74e0: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 HMOPEN
74f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7500: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e (18<<8)).#defin
7510: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
7520: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 HMSIZE
7530: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7540: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e (19<<8)).#defin
7550: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
7560: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 HMLOCK
7570: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7580: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (20<<8)).#defin
7590: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
75a0: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 HMMAP
75b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
75c0: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (21<<8)).#defin
75d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
75e0: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 EEK
75f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7600: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (22<<8)).#defin
7610: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
7620: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 ELETE_NOENT
7630: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7640: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (23<<8)).#defin
7650: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d e SQLITE_IOERR_M
7660: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 MAP
7670: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7680: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (24<<8)).#defin
7690: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 e SQLITE_IOERR_G
76a0: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 ETTEMPPATH
76b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
76c0: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (25<<8)).#defin
76d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
76e0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 ONVPATH
76f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7700: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (26<<8)).#defin
7710: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 e SQLITE_IOERR_V
7720: 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20 NODE
7730: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
7740: 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e (27<<8)).#defin
7750: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f e SQLITE_LOCKED_
7760: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 SHAREDCACHE
7770: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 (SQLITE_LOCKED
7780: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
7790: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 ne SQLITE_BUSY_R
77a0: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 ECOVERY
77b0: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
77c0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 | (1<<8)).#def
77d0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f ine SQLITE_BUSY_
77e0: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 SNAPSHOT
77f0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 (SQLITE_BUSY
7800: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 | (2<<8)).#de
7810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
7820: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 OPEN_NOTEMPDIR
7830: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
7840: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OPEN | (1<<8)).#
7850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
7860: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 NTOPEN_ISDIR
7870: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
7880: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 NTOPEN | (2<<8))
7890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
78a0: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 CANTOPEN_FULLPAT
78b0: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
78c0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 CANTOPEN | (3<<8
78d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
78e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 E_CANTOPEN_CONVP
78f0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
7900: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c E_CANTOPEN | (4<
7910: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7920: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 ITE_CORRUPT_VTAB
7930: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
7940: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 ITE_CORRUPT | (1
7950: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 LITE_READONLY_RE
7970: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 COVERY (SQ
7980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
7990: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
79a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
79b0: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 CANTLOCK (
79c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
79d0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
79e0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
79f0: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 Y_ROLLBACK
7a00: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
7a10: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 Y | (3<<8)).#def
7a20: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
7a30: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 NLY_DBMOVED
7a40: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
7a50: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 NLY | (4<<8)).#d
7a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
7a70: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 RT_ROLLBACK
7a80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f (SQLITE_ABO
7a90: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RT | (2<<8)).#de
7aa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
7ab0: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 TRAINT_CHECK
7ac0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
7ad0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 TRAINT | (1<<8))
7ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7af0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 CONSTRAINT_COMMI
7b00: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f THOOK (SQLITE_
7b10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c CONSTRAINT | (2<
7b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
7b40: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c OREIGNKEY (SQL
7b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
7b60: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
7b70: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
7b80: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 NT_FUNCTION
7b90: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
7ba0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 NT | (4<<8)).#de
7bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
7bc0: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 TRAINT_NOTNULL
7bd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
7be0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 TRAINT | (5<<8))
7bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7c00: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 CONSTRAINT_PRIMA
7c10: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f RYKEY (SQLITE_
7c20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c CONSTRAINT | (6<
7c30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 ITE_CONSTRAINT_T
7c50: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c RIGGER (SQL
7c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
7c70: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (7<<8)).#define
7c80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
7c90: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 NT_UNIQUE
7ca0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
7cb0: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 NT | (8<<8)).#de
7cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
7cd0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 TRAINT_VTAB
7ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
7cf0: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 TRAINT | (9<<8))
7d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7d10: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 CONSTRAINT_ROWID
7d20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
7d30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c CONSTRAINT |(10<
7d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7d50: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
7d60: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c ER_WAL (SQL
7d70: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c ITE_NOTICE | (1<
7d80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7d90: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
7da0: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c ER_ROLLBACK (SQL
7db0: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c ITE_NOTICE | (2<
7dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7dd0: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f ITE_WARNING_AUTO
7de0: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c INDEX (SQL
7df0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 ITE_WARNING | (1
7e00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7e10: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 LITE_AUTH_USER
7e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7e30: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c LITE_AUTH | (1<<
7e40: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8))../*.** CAPI3
7e50: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
7e60: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
7e70: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
7e80: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
7e90: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
7ea0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
7eb0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
7ec0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
7ed0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
7ee0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
7ef0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
7f00: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7f10: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 en] method..*/.#
7f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
7f30: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
7f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 0x00000001
7f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
7f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
7f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
7f80: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
7f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 0x00000002
7fa0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
7fb0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
7fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
7fd0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
7fe0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 0x00000004
7ff0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8000: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8020: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
8030: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 0x00000008
8040: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
8050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8060: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
8070: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 0x00000010
8080: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
8090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
80a0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 EN_AUTOPROXY
80b0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 0x00000020
80c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
80d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
80e0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 EN_URI
80f0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 0x00000040
8100: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8110: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8120: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8130: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 EN_MEMORY
8140: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 0x00000080
8150: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8160: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8180: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
8190: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 0x00000100
81a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
81b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
81c0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
81d0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 0x00000200
81e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
81f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8200: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
8210: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 0x00000400
8220: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
8230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8240: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
8250: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 0x00000800
8260: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
8270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8280: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
8290: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 0x00001000
82a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
82b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
82c0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
82d0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 0x00002000
82e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
82f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8300: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
8310: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 L 0x00004000
8320: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
8330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8340: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 EN_NOMUTEX
8350: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 0x00008000
8360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8390: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 EN_FULLMUTEX
83a0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 0x00010000
83b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
83c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
83d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
83e0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 EN_SHAREDCACHE
83f0: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 0x00020000
8400: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8410: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8430: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
8440: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 0x00040000
8450: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
8460: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
8470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
8480: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 EN_WAL
8490: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 0x00080000
84a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a /* VFS only */..
84b0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 /* Reserved:
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
84d0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 0x00F00000
84e0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
84f0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 EF: Device Chara
8500: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a cteristics.**.**
8510: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
8520: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
8530: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 od of the [sqlit
8540: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
8550: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 * object returns
8560: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
8570: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 h is a vector of
8580: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
8590: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
85a0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
85b0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
85c0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
85d0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
85e0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
85f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8600: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
8610: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
8620: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8630: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8640: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8650: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
8660: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8680: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
8690: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
86a0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
86b0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
86c0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
86d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
86e0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
86f0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
8700: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
8710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8730: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8740: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8750: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8760: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
8770: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8780: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
8790: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
87a0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
87b0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
87c0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
87d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
87e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
87f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
8800: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
8810: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
8820: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8830: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8840: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 * to xWrite().
8850: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8860: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
8870: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 RITE property me
8880: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 ans that.** afte
8890: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 r reboot followi
88a0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f ng a crash or po
88b0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e wer loss, the on
88c0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a ly bytes in a.**
88d0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 file that were
88e0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 written at the a
88f0: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c pplication level
8900: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e might have chan
8910: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ged.** and that
8920: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 adjacent bytes,
8930: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 even bytes withi
8940: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f n the same secto
8950: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 r are.** guarant
8960: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e eed to be unchan
8970: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 ged. The SQLITE
8980: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 _IOCAP_UNDELETAB
8990: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 LE_WHEN_OPEN.**
89a0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 flag indicate th
89b0: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 at a file cannot
89c0: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e be deleted when
89d0: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 open. The.** S
89e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
89f0: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 TABLE flag indic
8a00: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 ates that the fi
8a10: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 le is on.** read
8a20: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 -only media and
8a30: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 cannot be change
8a40: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 d even by proces
8a50: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 ses with.** elev
8a60: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e ated privileges.
8a70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
8a80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8aa0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
8ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8ac0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
8ad0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
8ae0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
8af0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
8b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
8b10: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
8b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
8b30: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 OMIC2K
8b40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 0x00000008.
8b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8b60: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 OCAP_ATOMIC4K
8b70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8b80: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
8b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8ba0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC8K
8bb0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 0x00000020.#d
8bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
8bd0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 AP_ATOMIC16K
8be0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8bf0: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
8c00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8c10: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 32K
8c20: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
8c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
8c40: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
8c50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
8c60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
8c70: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
8c80: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 END 0
8c90: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
8ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
8cb0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 EQUENTIAL
8cc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
8cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8ce0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
8cf0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 E_WHEN_OPEN 0x0
8d00: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 0000800.#define
8d10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
8d20: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
8d30: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 0x00001000.#
8d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
8d50: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 CAP_IMMUTABLE
8d60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
8d70: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 02000../*.** CAP
8d80: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b I3REF: File Lock
8d90: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a ing Levels.**.**
8da0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
8db0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
8dc0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
8dd0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
8de0: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
8df0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
8e00: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
8e10: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
8e20: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
8e30: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
8e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8e50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
8e60: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
8e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
8e80: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
8e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
8ea0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
8eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
8ec0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
8ed0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
8ee0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
8ef0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
8f00: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
8f10: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
8f20: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 gs.**.** When SQ
8f30: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
8f40: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
8f50: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
8f60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
8f70: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
8f80: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
8f90: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
8fa0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
8fb0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
8fc0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
8fd0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
8fe0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
8ff0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
9000: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
9010: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
9020: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
9030: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
9040: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
9050: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
9060: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 flushed. If the
9070: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
9080: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 of the flag.** e
9090: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
90a0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 _NORMAL, that me
90b0: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 ans to use norma
90c0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 l fsync() semant
90d0: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c ics..** If the l
90e0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 ower four bits e
90f0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
9100: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e _FULL, that mean
9110: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
9120: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
9130: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
9140: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f sync()..**.** Do
9150: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 not confuse the
9160: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
9170: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
9180: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a YNC_FULL flags.*
9190: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 * with the [PRAG
91a0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
91b0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 NORMAL and [PRAG
91c0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
91d0: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 FULL.** settings
91e0: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e . The [synchron
91f0: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 ous pragma] dete
9200: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c rmines when call
9210: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e s to the.** xSyn
9220: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 c VFS method occ
9230: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 ur and applies u
9240: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 niformly across
9250: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a all platforms..*
9260: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
9270: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
9280: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
9290: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f ags determine ho
92a0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f w.** energetic o
92b0: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f r rigorous or fo
92c0: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 rceful the sync
92d0: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 operations are a
92e0: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 nd.** only make
92f0: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 a difference on
9300: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 Mac OSX for the
9310: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 default SQLite c
9320: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 ode..** (Third-p
9330: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 arty VFS impleme
9340: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 ntations might a
9350: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 lso make the dis
9360: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
9370: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f een SQLITE_SYNC_
9380: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
9390: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 E_SYNC_FULL, but
93a0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 among the.** op
93b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 erating systems
93c0: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
93d0: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e ed by SQLite, on
93e0: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 ly Mac OSX.** ca
93f0: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 res about the di
9400: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 fference.).*/.#d
9410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
9420: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
9430: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
9440: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
9450: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
9460: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
9470: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
9480: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
9490: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
94a0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
94b0: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a ile Handle.**.**
94c0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
94d0: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
94e0: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
94f0: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 e in the .** [sq
9500: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 lite3_vfs | OS i
9510: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e nterface layer].
9520: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 Individual OS
9530: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 interface.** imp
9540: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
9550: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 l.** want to sub
9560: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 class this objec
9570: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 t by appending a
9580: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
9590: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 .** for their ow
95a0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 n use. The pMet
95b0: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 hods entry is a
95c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
95d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
95e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 hods] object tha
95f0: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 t defines method
9600: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 s for performing
9610: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f .** I/O operatio
9620: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 ns on the open f
9630: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ile..*/.typedef
9640: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
9650: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 ile sqlite3_file
9660: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
9670: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 _file {. const
9680: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
9690: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 o_methods *pMeth
96a0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 ods; /* Methods
96b0: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c for an open fil
96c0: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.};../*.** C
96d0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
96e0: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 rface File Virtu
96f0: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 al Methods Objec
9700: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 t.**.** Every fi
9710: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
9720: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
9730: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 pen] method popu
9740: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
9750: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
9760: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
9770: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
9780: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
9790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
97a0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
97b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
97c0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
97d0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
97e0: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
97f0: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
9800: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
9810: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
9820: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
9830: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
9840: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
9850: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 object..**.** I
9860: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
9870: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
9880: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
9890: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
98a0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
98b0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
98c0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
98d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
98e0: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
98f0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
9900: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 ven if the [sqli
9910: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 te3_vfs.xOpen] r
9920: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 eported that it
9930: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 failed. The.**
9940: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 only way to prev
9950: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 ent a call to xC
9960: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 lose following a
9970: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 failed [sqlite3
9980: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 _vfs.xOpen].** i
9990: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 s for the [sqlit
99a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f e3_vfs.xOpen] to
99b0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
99c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
99d0: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c lement.** to NUL
99e0: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
99f0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
9a00: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
9a10: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
9a20: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
9a30: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
9a40: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
9a50: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
9a60: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
9a70: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
9a80: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
9a90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
9aa0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
9ab0: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
9ac0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
9ad0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
9ae0: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
9af0: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
9b00: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
9b10: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
9b20: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
9b30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
9b40: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
9b50: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
9b60: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
9b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
9b80: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
9b90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
9ba0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
9bb0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
9bc0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
9bd0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
9be0: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
9bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
9c00: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
9c10: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
9c20: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
9c30: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
9c40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
9c50: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
9c60: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
9c70: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
9c80: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
9c90: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
9ca0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
9cb0: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
9cc0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
9cd0: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
9ce0: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
9cf0: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
9d00: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
9d10: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
9d20: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
9d30: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
9d40: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
9d50: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
9d60: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
9d70: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
9d80: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
9d90: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
9da0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
9db0: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
9dc0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
9dd0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
9de0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
9df0: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
9e00: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
9e10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
9e20: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
9e30: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
9e40: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
9e50: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
9e60: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
9e70: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
9e80: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
9e90: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
9ea0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
9eb0: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
9ec0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
9ed0: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
9ee0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
9ef0: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
9f00: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
9f10: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
9f20: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
9f30: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
9f40: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
9f50: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
9f60: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
9f70: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
9f80: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
9f90: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
9fa0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
9fb0: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
9fc0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
9fd0: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
9fe0: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
9ff0: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
a000: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 [file control op
a010: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 codes | list of
a020: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
a030: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
a040: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
a050: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
a060: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
a070: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
a080: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
a090: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
a0a0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
a0b0: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
a0c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
a0d0: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
a0e0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
a0f0: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
a100: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
a110: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
a120: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
a130: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
a140: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
a150: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
a160: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
a170: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
a180: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
a190: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
a1a0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
a1b0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
a1c0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
a1d0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
a1e0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
a1f0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
a200: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
a210: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
a220: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
a230: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
a240: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
a250: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
a260: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
a270: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
a280: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
a290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
a2a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
a2b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a2c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
a2d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a2e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
a2f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a300: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
a310: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a320: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
a330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a340: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
a350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
a360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
a370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
a390: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
a3a0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
a3b0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
a3c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
a3d0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c UENTIAL].** </ul
a3e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
a3f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
a400: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
a410: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
a420: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
a430: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
a440: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
a450: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
a460: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
a470: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
a480: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
a490: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
a4a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
a4b0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
a4c0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
a4d0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
a4e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
a4f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
a500: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
a510: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
a520: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
a530: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
a540: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
a550: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
a560: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
a570: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
a580: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
a590: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
a5a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
a5b0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
a5c0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
a5d0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
a5e0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
a5f0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
a600: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
a610: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
a620: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
a630: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
a640: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
a650: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
a660: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
a670: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
a680: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
a690: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
a6a0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
a6b0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
a6c0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
a6d0: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
a6e0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
a6f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
a700: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
a710: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
a720: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
a730: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
a740: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
a750: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
a760: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
a770: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
a780: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
a790: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
a7a0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
a7b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
a7c0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
a7d0: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
a7e0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
a7f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
a800: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
a810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
a820: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
a830: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
a840: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
a850: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
a860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
a870: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
a880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
a890: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a8a0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
a8b0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
a8c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
a8d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
a8e0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
a8f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
a900: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
a910: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
a920: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
a930: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
a940: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
a950: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
a960: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
a970: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
a980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
a990: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
a9a0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
a9b0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
a9c0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
a9d0: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
a9e0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
a9f0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
aa00: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
aa10: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
aa20: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
aa30: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
aa40: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
aa50: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
aa60: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
aa70: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
aa80: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
aa90: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
aaa0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
aab0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
aac0: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
aad0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
aae0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
aaf0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
ab00: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
ab10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
ab20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
ab30: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
ab40: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
ab50: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
ab60: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
ab70: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
ab80: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
ab90: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
aba0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
abb0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
abc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
abd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
abe0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
abf0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
ac00: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
ac10: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
ac20: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
ac30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
ac40: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
ac50: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 trol Opcodes.**
ac60: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 KEYWORDS: {file
ac70: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d control opcodes}
ac80: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f {file control o
ac90: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 pcode}.**.** The
aca0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
acb0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 ants are opcodes
acc0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f for the xFileCo
acd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 ntrol method.**
ace0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
acf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
ad00: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b ct and for the [
ad10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
ad20: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 trol()].** inter
ad30: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e face..**.** <ul>
ad40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
ad50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
ad60: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
ad70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
ad80: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
ad90: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
ada0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
adb0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
adc0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
add0: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
ade0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
adf0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
ae00: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
ae10: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
ae20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
ae30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
ae40: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
ae50: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
ae60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
ae70: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
ae80: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
ae90: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
aea0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
aeb0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
aec0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
aed0: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 testing and is
aee0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 only available w
aef0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hen the SQLITE_T
af00: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 EST.** compile-t
af10: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 ime option is us
af20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
af30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
af40: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 E_HINT]].** The
af50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
af60: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
af70: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
af80: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
af90: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
afa0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
afb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
afc0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
afd0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
afe0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
aff0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
b000: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
b010: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
b020: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
b030: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
b040: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
b050: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
b060: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
b070: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
b080: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
b090: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
b0a0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
b0b0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
b0c0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
b0d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b0e0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
b0f0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 IZE]].** The [SQ
b100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
b110: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 _SIZE] opcode is
b120: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 used to request
b130: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a that the VFS.**
b140: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 extends and tru
b150: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 ncates the datab
b160: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e ase file in chun
b170: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 ks of a size spe
b180: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
b190: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 user. The fourt
b1a0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 h argument to [s
b1b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b1c0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a rol()] should .*
b1d0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e * point to an in
b1e0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 teger (type int)
b1f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
b200: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 new chunk-size t
b210: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 o use.** for the
b220: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 nominated datab
b230: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 ase. Allocating
b240: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 database file sp
b250: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 ace in large.**
b260: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 chunks (say 1MB
b270: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 at a time), may
b280: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 reduce file-syst
b290: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e em fragmentation
b2a0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 and.** improve
b2b0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 performance on s
b2c0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a ome systems..**.
b2d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b2e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
b2f0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ER]].** The [SQL
b300: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
b310: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
b320: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
b330: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
b340: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
b350: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
b360: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 iated with a par
b370: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
b380: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
b390: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 See the [sqlite
b3a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
b3b0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
b3c0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
b3d0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
b3e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
b3f0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
b400: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e TTED]].** No lon
b410: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a ger in use..**.*
b420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b430: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 CNTL_SYNC]].** T
b440: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b450: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 _SYNC] opcode is
b460: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
b470: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 nally by SQLite
b480: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 and.** sent to t
b490: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 he VFS immediate
b4a0: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 ly before the xS
b4b0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e ync method is in
b4c0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 voked on a.** da
b4d0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 tabase file desc
b4e0: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 riptor. Or, if t
b4f0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 he xSync method
b500: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a is not invoked .
b510: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 ** because the u
b520: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 ser has configur
b530: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a ed SQLite with .
b540: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 ** [PRAGMA synch
b550: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 ronous | PRAGMA
b560: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d synchronous=OFF]
b570: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 it is invoked i
b580: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 n place .** of t
b590: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e he xSync method.
b5a0: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 In most cases,
b5b0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 the pointer argu
b5c0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 ment passed with
b5d0: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f .** this file-co
b5e0: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 ntrol is NULL. H
b5f0: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 owever, if the d
b600: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
b610: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 being synced.**
b620: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c as part of a mul
b630: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d ti-database comm
b640: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 it, the argument
b650: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c points to a nul
b660: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
b670: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
b680: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
b690: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c s master-journal
b6a0: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 file name. VFSe
b6b0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f s that .** do no
b6c0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
b6d0: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 al should silent
b6e0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
b6f0: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 pcode. Applicati
b700: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ons .** should n
b710: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 ot call [sqlite3
b720: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
b730: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 with this opcod
b740: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 e as doing so ma
b750: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 y .** disrupt th
b760: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
b770: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
b780: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 FSes that do req
b790: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a uire it. .**.**
b7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b7b0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
b7c0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TWO]].** The [SQ
b7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
b7e0: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f T_PHASETWO] opco
b7f0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 de is generated
b800: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 internally by SQ
b810: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 Lite.** and sent
b820: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 to the VFS afte
b830: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
b840: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 has been committ
b850: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a ed immediately.*
b860: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 * but before the
b870: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c database is unl
b880: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 ocked. VFSes tha
b890: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 t do not need th
b8a0: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f is signal.** sho
b8b0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
b8c0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
b8d0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
b8e0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a ould not call.**
b8f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
b900: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
b910: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
b920: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 ing so may disru
b930: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 pt the .** opera
b940: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
b950: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
b960: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
b970: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
b980: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
b990: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 32_AV_RETRY]].**
b9a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
b9b0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
b9c0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 RY] opcode is us
b9d0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 ed to configure
b9e0: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 automatic.** ret
b9f0: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e ry counts and in
ba00: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 tervals for cert
ba10: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 ain disk I/O ope
ba20: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a rations for the.
ba30: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d ** windows [VFS]
ba40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
ba50: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 vide robustness
ba60: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 in the presence
ba70: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 of.** anti-virus
ba80: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 programs. By d
ba90: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 efault, the wind
baa0: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 ows VFS will ret
bab0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a ry file read,.**
bac0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 file write, and
bad0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 file delete ope
bae0: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 rations up to 10
baf0: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 times, with a d
bb00: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 elay.** of 25 mi
bb10: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 lliseconds befor
bb20: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 e the first retr
bb30: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 y and with the d
bb40: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a elay increasing.
bb50: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f ** by an additio
bb60: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f nal 25 milliseco
bb70: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 nds with each su
bb80: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 bsequent retry.
bb90: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
bba0: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f allows these two
bbb0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 values (10 retr
bbc0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 ies and 25 milli
bbd0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 seconds of delay
bbe0: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 ).** to be adjus
bbf0: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 ted. The values
bc00: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 are changed for
bc10: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f all database co
bc20: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 nnections.** wit
bc30: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f hin the same pro
bc40: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d cess. The argum
bc50: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
bc60: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 to an array of
bc70: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 two.** integers
bc80: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 where the first
bc90: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 integer i the ne
bca0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e w retry count an
bcb0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 d the second.**
bcc0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 integer is the d
bcd0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 elay. If either
bce0: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 integer is nega
bcf0: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 tive, then the s
bd00: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 etting.** is not
bd10: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 changed but ins
bd20: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 tead the prior v
bd30: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 alue of that set
bd40: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a ting is written.
bd50: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 ** into the arra
bd60: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e y entry, allowin
bd70: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 g the current re
bd80: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 try settings to
bd90: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 be.** interrogat
bda0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 ed. The zDbName
bdb0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 parameter is ig
bdc0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 nored..**.** <li
bdd0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bde0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a PERSIST_WAL]].**
bdf0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
be00: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d NTL_PERSIST_WAL]
be10: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
be20: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 to set or query
be30: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e the.** persisten
be40: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 t [WAL | Write A
be50: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e head Log] settin
be60: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 g. By default,
be70: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a the auxiliary.**
be80: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 write ahead log
be90: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f and shared memo
bea0: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f ry files used fo
beb0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f r transaction co
bec0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 ntrol.** are aut
bed0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
bee0: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 ed when the late
bef0: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f st connection to
bf00: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
bf10: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e closes. Settin
bf20: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c g persistent WAL
bf30: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f mode causes tho
bf40: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 se files to pers
bf50: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f ist after.** clo
bf60: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 se. Persisting
bf70: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 the files is use
bf80: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 ful when other p
bf90: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f rocesses that do
bfa0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 not.** have wri
bfb0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e te permission on
bfc0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 the directory c
bfd0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 ontaining the da
bfe0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 tabase file want
bff0: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 .** to read the
c000: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 database file, a
c010: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 s the WAL and sh
c020: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 ared memory file
c030: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 s must exist.**
c040: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 in order for the
c050: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 database to be
c060: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 readable. The f
c070: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
c080: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
c090: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
c0a0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
c0b0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
c0c0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
c0d0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
c0e0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
c0f0: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c e persistent WAL
c100: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e mode or 1 to en
c110: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a able persistent.
c120: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 ** WAL mode. If
c130: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 the integer is
c140: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f -1, then it is o
c150: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 verwritten with
c160: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 the current.** W
c170: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 AL persistence s
c180: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c etting..**.** <l
c190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c1a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
c1b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b RITE]].** ^The [
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
c1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
c1e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
c1f0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
c200: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
c210: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 nt "powersafe-ov
c220: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f erwrite" or "PSO
c230: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 W" setting. The
c240: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a PSOW setting.**
c250: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 determines the
c260: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f [SQLITE_IOCAP_PO
c270: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
c280: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a E] bit of the.**
c290: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
c2a0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e ristics methods.
c2b0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
c2c0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
c2d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c2e0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 l()] for this op
c2f0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 code should be a
c300: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
c310: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 nteger..** That
c320: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 integer is 0 to
c330: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d disable zero-dam
c340: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f age mode or 1 to
c350: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d enable zero-dam
c360: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 age.** mode. If
c370: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 the integer is
c380: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f -1, then it is o
c390: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 verwritten with
c3a0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a the current.** z
c3b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 ero-damage mode
c3c0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
c3d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
c3e0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a L_OVERWRITE]].**
c3f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
c400: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f NTL_OVERWRITE] o
c410: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 pcode is invoked
c420: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 by SQLite after
c430: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 opening.** a wr
c440: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ite transaction
c450: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
c460: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 , unless it is r
c470: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 olled back for s
c480: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 ome.** reason, t
c490: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 he entire databa
c4a0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 se file will be
c4b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 overwritten by t
c4c0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 he current .** t
c4d0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 ransaction. This
c4e0: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 is used by VACU
c4f0: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a UM operations..*
c500: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c510: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d E_FCNTL_VFSNAME]
c520: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
c530: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d E_FCNTL_VFSNAME]
c540: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 opcode can be u
c550: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
c560: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c e names of.** al
c570: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 l [VFSes] in the
c580: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 VFS stack. The
c590: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c names are of al
c5a0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 l VFS shims and
c5b0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 the.** final bot
c5c0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 tom-level VFS ar
c5d0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d e written into m
c5e0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
c5f0: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rom .** [sqlite3
c600: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 _malloc()] and t
c610: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f he result is sto
c620: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a red in the char*
c630: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 variable.** tha
c640: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 t the fourth par
c650: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 ameter of [sqlit
c660: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
c670: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a )] points to..**
c680: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 The caller is r
c690: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 esponsible for f
c6a0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 reeing the memor
c6b0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 y when done. As
c6c0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c with.** all fil
c6d0: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e e-control action
c6e0: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 s, there is no g
c6f0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
c700: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 is will actually
c710: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e .** do anything.
c720: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 Callers should
c730: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 initialize the
c740: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 char* variable t
c750: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e o a NULL.** poin
c760: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 ter in case this
c770: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
c780: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 not implemented
c790: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e . This file-con
c7a0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e trol.** is inten
c7b0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 ded for diagnost
c7c0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a ic use only..**.
c7d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
c7e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a FCNTL_PRAGMA]].*
c7f0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 * ^Whenever a [P
c800: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 RAGMA] statement
c810: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b is parsed, an [
c820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
c830: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f GMA] .** file co
c840: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f ntrol is sent to
c850: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 the open [sqlit
c860: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
c870: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a corresponding.**
c880: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
c890: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 file to which t
c8a0: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d he pragma statem
c8b0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 ent refers. ^The
c8c0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
c8d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
c8e0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
c8f0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 ontrol is an arr
c900: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 ay of.** pointer
c910: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 s to strings (ch
c920: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 ar**) in which t
c930: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e he second elemen
c940: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a t of the array.*
c950: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
c960: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 the pragma and
c970: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e the third elemen
c980: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
c990: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 t to the.** prag
c9a0: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 ma or NULL if th
c9b0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 e pragma has no
c9c0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 argument. ^The
c9d0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a handler for an.*
c9e0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
c9f0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e PRAGMA] file con
ca00: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 trol can optiona
ca10: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 lly make the fir
ca20: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 st element.** of
ca30: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 the char** argu
ca40: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 ment point to a
ca50: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 string obtained
ca60: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 from [sqlite3_mp
ca70: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 rintf()].** or t
ca80: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e he equivalent an
ca90: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 d that string wi
caa0: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 ll become the re
cab0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 sult of the prag
cac0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 ma or.** the err
cad0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 or message if th
cae0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 e pragma fails.
caf0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
cb00: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
cb10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
cb20: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f turns [SQLITE_NO
cb30: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f TFOUND], then no
cb40: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 rmal .** [PRAGMA
cb50: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e ] processing con
cb60: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 tinues. ^If the
cb70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
cb80: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 RAGMA].** file c
cb90: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
cba0: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e SQLITE_OK], then
cbb0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 the parser assu
cbc0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
cbd0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 VFS has handled
cbe0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c the PRAGMA itsel
cbf0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 f and the parser
cc00: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d generates a no-
cc10: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 op.** prepared s
cc20: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 tatement if resu
cc30: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c lt string is NUL
cc40: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 L, or that retur
cc50: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 ns a copy.** of
cc60: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e the result strin
cc70: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 g if the string
cc80: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 is non-NULL..**
cc90: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
cca0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
ccb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
ccc0: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 ns.** any result
ccd0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e code other than
cce0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
ccf0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
cd00: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a ], that means.**
cd10: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e that the VFS en
cd20: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 countered an err
cd30: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e or while handlin
cd40: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 g the [PRAGMA] a
cd50: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c nd the.** compil
cd60: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 ation of the PRA
cd70: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 GMA fails with a
cd80: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b n error. ^The [
cd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
cda0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e GMA].** file con
cdb0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 trol occurs at t
cdc0: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
cdd0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 pragma statement
cde0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f analysis and so
cdf0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 .** it is able t
ce00: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 o override built
ce10: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 -in [PRAGMA] sta
ce20: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c tements..**.** <
ce30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ce40: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a L_BUSYHANDLER]].
ce50: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
ce60: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
ce70: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 R].** file-contr
ce80: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ol may be invoke
ce90: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 d by SQLite on t
cea0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
ceb0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 handle.** short
cec0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f ly after it is o
ced0: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 pened in order t
cee0: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 o provide a cust
cef0: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 om VFS with acce
cf00: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e ss.** to the con
cf10: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 nections busy-ha
cf20: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 ndler callback.
cf30: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
cf40: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a of type (void **
cf50: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 ).** - an array
cf60: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 of two (void *)
cf70: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 values. The firs
cf80: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 t (void *) actua
cf90: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f lly points.** to
cfa0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
cfb0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 ype (int (*)(voi
cfc0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 d *)). In order
cfd0: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f to invoke the co
cfe0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 nnections.** bus
cff0: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 y-handler, this
d000: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
d010: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
d020: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 the second (void
d030: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 *) in.** the ar
d040: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ray as the only
d050: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 argument. If it
d060: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
d070: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 , then the opera
d080: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
d090: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 e retried. If it
d0a0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
d0b0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 he custom VFS sh
d0c0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 ould abandon the
d0d0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 .** current oper
d0e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
d0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
d100: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a TEMPFILENAME]].*
d110: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 * ^Application c
d120: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 an invoke the [S
d130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
d140: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 FILENAME] file-c
d150: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 ontrol.** to hav
d160: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 e SQLite generat
d170: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 e a.** temporary
d180: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 filename using
d190: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 the same algorit
d1a0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f hm that is follo
d1b0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a wed to generate.
d1c0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
d1d0: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 enames for TEMP
d1e0: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 tables and other
d1f0: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 internal uses.
d200: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 The.** argument
d210: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 should be a cha
d220: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 r** which will b
d230: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 e filled with th
d240: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 e filename.** wr
d250: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
d260: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
d270: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
d280: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 )]. The caller
d290: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 should.** invoke
d2a0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
d2b0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 ] on the result
d2c0: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 to avoid a memor
d2d0: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c y leak..**.** <l
d2e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
d2f0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
d300: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d310: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
d320: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e control is use
d330: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 d to query or se
d340: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d t the.** maximum
d350: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
d360: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 that will be us
d370: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 ed for memory-ma
d380: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 pped I/O..** The
d390: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
d3a0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 ointer to a valu
d3b0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 e of type sqlite
d3c0: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 3_int64 that.**
d3d0: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d is an advisory m
d3e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
d3f0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
d400: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 le to memory map
d410: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 . The.** pointe
d420: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e r is overwritten
d430: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 with the old va
d440: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 lue. The limit
d450: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 is not changed i
d460: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f f.** the value o
d470: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 riginally pointe
d480: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 d to is negative
d490: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 , and so the cur
d4a0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 rent limit .** c
d4b0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 an be queried by
d4c0: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f passing in a po
d4d0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 inter to a negat
d4e0: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 ive number. Thi
d4f0: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f s.** file-contro
d500: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e l is used intern
d510: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e ally to implemen
d520: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 t [PRAGMA mmap_s
d530: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ize]..**.** <li>
d540: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
d550: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 RACE]].** The [S
d560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 QLITE_FCNTL_TRAC
d570: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 E] file control
d580: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 provides advisor
d590: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a y information.**
d5a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 to the VFS abou
d5b0: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 t what the highe
d5c0: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 r layers of the
d5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 SQLite stack are
d5e0: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 doing..** This
d5f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
d600: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 used by some VFS
d610: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e activity tracin
d620: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 g [shims]..** Th
d630: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
d640: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
d650: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 string. Higher
d660: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a layers in the.**
d670: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 SQLite stack ma
d680: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 y generate insta
d690: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c nces of this fil
d6a0: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 e control if.**
d6b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
d6c0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d FCNTL_TRACE] com
d6d0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
d6e0: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a is enabled..**.
d6f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
d700: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
d710: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
d720: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
d730: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
d740: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 nterprets its ar
d750: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 gument as a.** p
d760: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
d770: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 eger and it writ
d780: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 es a boolean int
d790: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 o that integer d
d7a0: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 epending.** on w
d7b0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
d7c0: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 e file has been
d7d0: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 renamed, moved,
d7e0: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 or deleted since
d7f0: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 it.** was first
d800: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c opened..**.** <
d810: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d820: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
d830: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c LE]].** The [SQL
d840: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
d850: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f SET_HANDLE] opco
d860: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
d870: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
d880: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
d890: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
d8a0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 l method to swap
d8b0: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 the file handle
d8c0: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a with the one.**
d8d0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
d8e0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
d8f0: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 . This capabili
d900: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ty is used durin
d910: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 g testing.** and
d920: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
d930: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
d940: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 SQLITE_TEST is
d950: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
d960: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d970: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a L_WAL_BLOCK]].**
d980: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
d990: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 TL_WAL_BLOCK] is
d9a0: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 a signal to the
d9b0: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 VFS layer that
d9c0: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 it might.** be a
d9d0: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 dvantageous to b
d9e0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 lock on the next
d9f0: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 WAL lock if the
da00: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d lock is not imm
da10: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 ediately.** avai
da20: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 lable. The WAL
da30: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 subsystem issues
da40: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 this signal dur
da50: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 ing rare.** circ
da60: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 umstances in ord
da70: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 er to fix a prob
da80: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 lem with priorit
da90: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 y inversion..**
daa0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
dab0: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e uld <em>not</em>
dac0: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 use this file-c
dad0: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ontrol..**.** <l
dae0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
daf0: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 _ZIPVFS]].** The
db00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a [SQLITE_FCNTL_Z
db10: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 IPVFS] opcode is
db20: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
db30: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c zipvfs only. All
db40: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 other.** VFS sh
db50: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 ould return SQLI
db60: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 TE_NOTFOUND for
db70: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a this opcode..**.
db80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
db90: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 FCNTL_RBU]].** T
dba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
dbb0: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 _RBU] opcode is
dbc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 implemented by t
dbd0: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 he special VFS u
dbe0: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 sed by.** the RB
dbf0: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 U extension only
dc00: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 . All other VFS
dc10: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 should return S
dc20: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 QLITE_NOTFOUND f
dc30: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 or.** this opcod
dc40: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f e. .** </ul>.*/
dc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dc60: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
dc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
dc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dc90: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_GET_LOCKPRO
dca0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 XYFILE 2.#
dcb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dcc0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_SET_LOCKPROX
dcd0: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 YFILE 3.#d
dce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
dcf0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 TL_LAST_ERRNO
dd00: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
dd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
dd20: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
dd30: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
dd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
dd50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
dd60: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
dd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
dd80: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
dd90: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
dda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
ddb0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
ddc0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
ddd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
dde0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
ddf0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
de00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
de10: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
de20: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
de30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
de40: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
de50: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
de60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
de70: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
de80: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
de90: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
dea0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
deb0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 13.#define SQLI
dec0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 TE_FCNTL_PRAGMA
ded0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
dee0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 14.#define SQLIT
def0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
df00: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 LER 1
df10: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
df20: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
df30: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 AME 16
df40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
df50: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 FCNTL_MMAP_SIZE
df60: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 18.
df70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
df80: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 CNTL_TRACE
df90: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 19.#
dfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dfb0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 NTL_HAS_MOVED
dfc0: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 20.#d
dfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
dfe0: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 TL_SYNC
dff0: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 21.#de
e000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
e010: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 L_COMMIT_PHASETW
e020: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 O 22.#def
e030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e040: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
e050: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 E 23.#defi
e060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e070: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 WAL_BLOCK
e080: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 24.#defin
e090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a e SQLITE_FCNTL_Z
e0a0: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 IPVFS
e0b0: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 25.#define
e0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 SQLITE_FCNTL_RB
e0d0: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 U
e0e0: 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 26../* depr
e0f0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a ecated names */.
e100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
e110: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
e120: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e SQLITE_FCN
e130: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_GET_LOCKPROXY
e140: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c FILE.#define SQL
e150: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_SET_LOCKPROX
e160: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 YFILE SQLIT
e170: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b E_FCNTL_SET_LOCK
e180: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e PROXYFILE.#defin
e190: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
e1a0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
e1b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 SQLITE_FCNTL_LAS
e1c0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 T_ERRNO.../*.**
e1d0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
e1e0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 Handle.**.** The
e1f0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
e200: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
e210: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
e220: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
e230: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
e240: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
e250: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
e260: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
e270: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
e280: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
e290: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
e2a0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
e2b0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
e2c0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
e2d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
e2e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
e2f0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
e300: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
e310: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
e320: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
e330: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
e340: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
e350: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e360: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a OS Interface Obj
e370: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ect.**.** An ins
e380: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
e390: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
e3a0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
e3b0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
e3c0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
e3d0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
e3e0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
e3f0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
e400: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
e410: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
e420: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
e430: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 l file system".
e440: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 See.** the [VFS
e450: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 | VFS documenta
e460: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 tion] for furthe
e470: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a r information..*
e480: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
e490: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
e4a0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
e4b0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
e4c0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
e4d0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
e4e0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
e4f0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
e500: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
e510: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
e520: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
e530: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
e540: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
e550: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
e560: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
e570: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
e580: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
e590: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
e5a0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
e5b0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
e5c0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
e5d0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
e5e0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
e5f0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
e600: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
e610: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
e620: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
e630: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
e640: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
e650: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
e660: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
e670: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
e680: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
e690: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
e6a0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
e6b0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
e6c0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
e6d0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
e6e0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
e6f0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
e700: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
e710: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
e720: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
e730: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
e740: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
e750: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
e760: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
e770: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
e780: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
e790: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
e7a0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
e7b0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
e7c0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
e7d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
e7e0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
e7f0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
e800: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
e810: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
e820: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
e830: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
e840: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
e850: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
e860: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
e870: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
e880: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
e890: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
e8a0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
e8b0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
e8c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
e8d0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
e8e0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
e8f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
e900: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
e910: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
e920: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
e930: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
e940: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
e950: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
e960: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
e970: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
e980: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
e990: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
e9a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
e9b0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 xOpen]].** ^SQLi
e9c0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
e9d0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
e9e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
e9f0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
ea00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
ea10: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
ea20: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
ea30: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 Pathname() with
ea40: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 an optional suff
ea50: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 ix added..** ^If
ea60: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 a suffix is add
ea70: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e ed to the zFilen
ea80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 ame parameter, i
ea90: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 t will.** consis
eaa0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d t of a single "-
eab0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c " character foll
eac0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 owed by no more
ead0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 than.** 11 alpha
eae0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 numeric and/or "
eaf0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -" characters..*
eb00: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 * ^SQLite furthe
eb10: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 r guarantees tha
eb20: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 t.** the string
eb30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e will be valid an
eb40: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 d unchanged unti
eb50: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a l xClose() is.**
eb60: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 called. Because
eb70: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 of the previous
eb80: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 sentence,.** th
eb90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
eba0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 can safely stor
ebb0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 e a pointer to t
ebc0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 he.** filename i
ebd0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 f it needs to re
ebe0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e member the filen
ebf0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ame for some rea
ec00: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a son..** If the z
ec10: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
ec20: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 er to xOpen is a
ec30: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
ec40: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 en xOpen.** must
ec50: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 invent its own
ec60: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 temporary name f
ec70: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 or the file. ^W
ec80: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 henever the .**
ec90: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 xFilename parame
eca0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 ter is NULL it w
ecb0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 ill also be the
ecc0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a case that the.**
ecd0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
ece0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 will include [S
ecf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
ed00: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a EONCLOSE]..**.**
ed10: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
ed20: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
ed30: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
ed40: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
ed50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
ed60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
ed70: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
ed80: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
ed90: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
eda0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
edb0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
edc0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
edd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
ede0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
edf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
ee00: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f .** If xOpen() o
ee10: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 pens a file read
ee20: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 -only then it se
ee30: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f ts *pOutFlags to
ee40: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c .** include [SQL
ee50: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
ee60: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 Y]. Other bits
ee70: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 in *pOutFlags ma
ee80: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 y be set..**.**
ee90: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^(SQLite will al
eea0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
eeb0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
eec0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
eed0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
eee0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
eef0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
ef00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
ef10: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
ef20: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
ef30: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
ef40: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
ef50: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
ef60: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
ef70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ef80: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
ef90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
efa0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
efb0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
efc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
efd0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
efe0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
eff0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
f000: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
f010: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e EN_WAL].** </ul>
f020: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c )^.**.** The fil
f030: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 e I/O implementa
f040: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 tion can use the
f050: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 object type fla
f060: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 gs to.** change
f070: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
f080: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
f090: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
f0a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
f0b0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
f0c0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
f0d0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
f0e0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 might make.** t
f0f0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 he open of a jou
f100: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f rnal file a no-o
f110: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 p. Writes to th
f120: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 is journal would
f130: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f .** also be no-o
f140: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 ps, and any atte
f150: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 mpt to read the
f160: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 journal would re
f170: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 turn.** SQLITE_I
f180: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
f190: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
f1a0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
f1b0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 t a database.**
f1c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 file will be doi
f1d0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 ng page-aligned
f1e0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 sector reads and
f1f0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e writes in a ran
f200: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 dom.** order and
f210: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 set up its I/O
f220: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 subsystem accord
f230: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ingly..**.** SQL
f240: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 ite might also a
f250: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
f260: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
f270: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
f280: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
f290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
f2a0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
f2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
f2c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
f2d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
f2e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
f2f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
f300: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
f310: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a file should be.*
f320: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 * deleted when i
f330: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 t is closed. ^T
f340: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
f350: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
f360: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f * will be set fo
f370: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 r TEMP databases
f380: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e and their journ
f390: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a als, transient.*
f3a0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 * databases, and
f3b0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
f3c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
f3d0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
f3e0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
f3f0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
f400: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
f410: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
f420: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
f430: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
f440: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
f450: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
f460: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
f470: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
f480: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
f490: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
f4a0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
f4b0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
f4c0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
f4d0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
f4e0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
f4f0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
f500: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
f510: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
f520: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
f530: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
f540: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
f550: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
f560: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
f570: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
f580: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
f590: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
f5a0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 * ^At least szOs
f5b0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
f5c0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
f5d0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
f5e0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
f5f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
f600: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
f610: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
f620: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
f630: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f The xOpen metho
f640: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 d does not have
f650: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 to.** allocate t
f660: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 he structure; it
f670: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c should just fil
f680: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 l it in. Note t
f690: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e hat.** the xOpen
f6a0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 method must set
f6b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
f6c0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 e.pMethods to ei
f6d0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 ther.** a valid
f6e0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
f6f0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 ods] object or t
f700: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d o NULL. xOpen m
f710: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 ust do.** this e
f720: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 ven if the open
f730: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 fails. SQLite e
f740: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 xpects that the
f750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
f760: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 thods.** element
f770: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
f780: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 fter xOpen retur
f790: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ns regardless of
f7a0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 the success.**
f7b0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
f7c0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a e xOpen call..**
f7d0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
f7e0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e s.xAccess]].** ^
f7f0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
f800: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
f810: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
f820: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
f830: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
f840: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
f850: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
f860: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
f870: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
f880: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
f890: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
f8a0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
f8b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
f8c0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
f8d0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
f8e0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
f8f0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
f900: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
f910: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 .**.** ^SQLite w
f920: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
f930: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
f940: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 athname+1 bytes
f950: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 for the.** outpu
f960: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 t buffer xFullPa
f970: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 thname. The exa
f980: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f ct size of the o
f990: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
f9a0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 is also passed a
f9b0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f s a parameter to
f9c0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 both methods.
f9d0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
f9e0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
f9f0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
fa00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
fa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
fa20: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
fa30: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
fa40: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
fa50: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
fa60: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
fa70: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
fa80: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
fa90: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
faa0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
fab0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
fac0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
fad0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
fae0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 eep(), xCurrentT
faf0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 ime(), and xCurr
fb00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a entTimeInt64().*
fb10: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 * interfaces are
fb20: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
fb30: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
fb40: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
fb50: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
fb60: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
fb70: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
fb80: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
fb90: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
fba0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
fbb0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
fbc0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
fbd0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
fbe0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
fbf0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
fc00: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
fc10: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
fc20: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
fc30: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 obtained..** The
fc40: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
fc50: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
fc60: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
fc70: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
fc80: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
fc90: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
fca0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 iven. ^The xCur
fcb0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
fcc0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
fcd0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
fce0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
fcf0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 date and time a
fd00: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 s.** a floating
fd10: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 point value..**
fd20: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
fd30: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
fd40: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 returns, as an i
fd50: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 nteger, the Juli
fd60: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 an.** Day Number
fd70: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 multiplied by 8
fd80: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
fd90: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
fda0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
fdb0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
fdc0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
fdd0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
fde0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
fdf0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
fe00: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
fe10: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
fe20: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
fe30: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
fe40: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
fe50: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
fe60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
fe70: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
fe80: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
fe90: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
fea0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
feb0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
fec0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
fed0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
fee0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
fef0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
ff00: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
ff10: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
ff20: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
ff30: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
ff40: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
ff50: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
ff60: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
ff70: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
ff80: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
ff90: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
ffa0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
ffb0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
ffc0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
ffd0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
ffe0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
fff0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
10000 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
10010 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
10020 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
10030 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
10040 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
10050 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
10060 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
10070 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
10080 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
10090 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
100a0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
100b0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
100c0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
100d0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
100e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
100f0 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
10100 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
10110 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
10120 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
10130 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
10140 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
10150 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
10160 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
10170 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
10180 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
10190 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
101a0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
101b0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
101c0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
101d0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
101e0 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
101f0 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
10200 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
10210 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
10220 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
10230 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
10240 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
10250 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
10260 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
10270 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
10280 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
10290 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
102a0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
102b0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
102c0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
102d0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
102e0 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
102f0 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
10300 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
10310 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
10320 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
10330 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
10340 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
10350 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
10360 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
10370 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
10380 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
10390 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
103a0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
103b0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
103c0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
103d0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
103e0 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
103f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10410 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
10420 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
10430 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
10440 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
10450 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
10460 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
10470 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
10480 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
10490 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
104a0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
104b0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
104d0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
104e0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
104f0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
10500 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
10510 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
10520 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
10530 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
10540 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
10550 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
10560 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
10570 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
10580 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
10590 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
105a0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
105b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
105c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
105d0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
105e0 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
105f0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
10600 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
10610 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
10620 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
10630 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
10640 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
10650 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
10660 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
10670 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
10680 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
10690 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
106a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
106b0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
106c0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
106d0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
106e0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
106f0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
10700 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
10710 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
10720 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
10730 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
10740 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
10750 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
10760 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
10770 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
10780 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
10790 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
107a0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
107b0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
107c0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
107d0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
107e0 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
107f0 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
10800 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
10810 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
10820 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
10830 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
10840 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
10850 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
10860 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
10870 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
10880 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
10890 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
108a0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
108b0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
108c0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
108d0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
108e0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
108f0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
10900 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
10910 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
10920 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
10930 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
10940 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
10950 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
10960 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
10970 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
10980 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
10990 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
109a0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
109b0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
109c0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
109d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
109e0 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
109f0 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
10a00 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
10a10 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
10a20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
10a30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
10a40 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
10a50 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
10a60 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
10a70 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
10a80 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
10a90 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
10aa0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
10ab0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
10ac0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
10ad0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
10ae0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10af0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
10b00 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
10b10 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
10b20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
10b30 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
10b40 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10b50 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10b60 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
10b70 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
10b80 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
10b90 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
10ba0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
10bb0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
10bc0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
10bd0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
10be0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
10bf0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
10c00 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
10c10 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
10c20 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
10c30 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
10c40 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
10c50 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
10c60 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
10c70 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
10c80 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
10c90 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
10ca0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
10cb0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10cc0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10cd0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
10ce0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
10cf0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
10d00 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
10d10 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
10d20 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
10d30 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
10d40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
10d50 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
10d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10d70 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
10d80 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
10d90 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
10da0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
10db0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
10dc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
10dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10de0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
10df0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
10e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10e10 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
10e20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
10e30 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
10e40 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10e50 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
10e60 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
10e70 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
10e80 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
10e90 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
10ea0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
10eb0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
10ec0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
10ed0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
10ee0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
10ef0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
10f00 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
10f10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
10f20 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
10f30 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
10f40 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10f50 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
10f60 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
10f70 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10f80 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
10f90 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
10fa0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
10fb0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
10fd0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
10fe0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
10ff0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
11000 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
11010 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
11020 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
11030 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 ven on the corre
11040 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
11050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
11060 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
11070 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
11080 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
11090 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
110a0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
110b0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
110c0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
110d0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
110e0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
110f0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
11100 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
11110 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
11120 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
11130 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
11140 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
11150 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
11160 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
11170 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
11180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
11190 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
111a0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
111b0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
111c0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
111d0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
111e0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
111f0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
11200 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
11210 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
11220 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
11230 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
11240 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
11250 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
11260 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
11270 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
11280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
11290 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
112a0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
112b0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
112c0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
112d0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
112e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
112f0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
11300 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
11310 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
11320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
11330 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
11340 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
11350 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
11360 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
11370 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
11380 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
11390 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
113a0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
113b0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
113c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
113d0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
113e0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
113f0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
11400 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
11410 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
11420 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
11430 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
11440 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
11450 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
11460 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
11470 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
11480 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
11490 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
114a0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
114b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
114c0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
114d0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
114e0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
114f0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
11500 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
11510 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
11520 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
11530 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
11540 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
11550 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
11560 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
11570 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
11580 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
11590 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
115a0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
115b0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
115c0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
115d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
115e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
115f0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
11600 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
11610 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
11620 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
11630 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
11640 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
11650 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
11660 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
11670 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
11680 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11690 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
116a0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
116b0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
116c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
116d0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
116e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
116f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
11700 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11710 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
11720 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
11730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11740 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
11750 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
11760 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
11770 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
11780 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
11790 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
117a0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
117b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
117c0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
117d0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
117e0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
117f0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
11800 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
11810 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
11820 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
11830 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
11840 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
11850 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
11860 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
11870 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
11880 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
11890 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
118a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
118b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
118c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
118d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
118e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
118f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
11900 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
11910 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
11920 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11930 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
11940 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
11950 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
11960 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
11970 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
11980 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
11990 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
119a0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
119b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
119c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
119d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
119e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
119f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
11a00 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
11a10 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
11a20 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
11a30 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
11a40 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
11a50 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
11a60 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
11a70 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11a80 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
11a90 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
11aa0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
11ab0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
11ac0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
11ad0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
11ae0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
11af0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
11b00 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
11b10 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
11b20 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
11b30 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
11b40 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
11b50 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
11b60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11b70 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
11b80 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
11b90 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
11ba0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
11bb0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
11bc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
11bd0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
11be0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
11bf0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
11c00 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
11c10 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
11c20 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
11c30 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
11c40 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
11c50 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
11c60 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
11c70 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
11c80 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
11c90 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
11ca0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11cb0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
11cc0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
11cd0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
11ce0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
11cf0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
11d00 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
11d10 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
11d20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
11d30 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
11d40 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
11d50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11d60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
11d70 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
11d80 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
11d90 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
11da0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
11db0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
11dc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
11dd0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
11de0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
11df0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
11e00 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
11e10 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
11e20 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
11e30 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
11e40 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
11e50 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
11e60 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
11e70 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
11e80 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
11e90 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
11ea0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
11eb0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
11ec0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
11ed0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
11ee0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
11ef0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
11f00 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
11f10 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
11f20 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
11f30 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
11f40 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
11f50 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
11f60 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
11f70 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
11f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
11f90 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
11fa0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
11fb0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
11fc0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
11fd0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
11fe0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
11ff0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
12000 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
12010 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
12020 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
12030 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
12040 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
12050 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
12060 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
12070 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12080 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
12090 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
120a0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
120b0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
120c0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
120d0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
120e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
120f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
12100 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
12110 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
12120 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
12130 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
12140 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
12150 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
12160 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
12170 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
12180 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
12190 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
121a0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
121b0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
121c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
121d0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
121e0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
121f0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
12200 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
12210 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
12220 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
12230 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
12240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
12250 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
12260 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
12270 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
12280 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
12290 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
122a0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
122b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
122c0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 failure..*/.SQLI
122d0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
122e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
122f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 3_initialize(voi
12300 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 d);.SQLITE_API i
12310 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
12320 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f L sqlite3_shutdo
12330 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 wn(void);.SQLITE
12340 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
12350 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
12360 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 os_init(void);.S
12370 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
12380 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
12390 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
123a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
123b0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
123c0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
123d0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
123e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
123f0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
12400 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
12410 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
12420 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
12430 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
12440 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
12450 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
12460 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
12470 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
12480 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
12490 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
124a0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
124b0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
124c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
124d0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
124e0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
124f0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
12500 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
12510 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
12520 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
12530 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 * <b>The sqlite3
12540 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
12550 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 ace is not threa
12560 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 dsafe. The appli
12570 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 cation.** must e
12580 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
12590 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
125a0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
125b0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
125c0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
125d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
125e0 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a running.</b>.**.
125f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
12600 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
12610 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 e.** may only be
12620 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 invoked prior t
12630 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 o library initia
12640 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a lization using.*
12650 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 * [sqlite3_initi
12660 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
12670 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 r shutdown by [s
12680 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12690 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 )]..** ^If sqlit
126a0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 e3_config() is c
126b0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
126c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
126d0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a )] and before.**
126e0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
126f0 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 wn()] then it wi
12700 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 ll return SQLITE
12710 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 _MISUSE..** Note
12720 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 , however, that
12730 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 ^sqlite3_config(
12740 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 ) can be called
12750 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a as part of the.*
12760 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
12770 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 of an applicati
12780 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 on-defined [sqli
12790 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a te3_os_init()]..
127a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
127b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
127c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
127d0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 an integer.** [c
127e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
127f0 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
12800 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
12810 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
12820 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
12830 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
12840 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
12850 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
12860 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 the [configurati
12870 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
12880 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
12890 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e ent..**.** ^When
128a0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e a configuration
128b0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 option is set,
128c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
128d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
128e0 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 _OK]..** ^If the
128f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f option is unkno
12900 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 wn or SQLite is
12910 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 unable to set th
12920 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e e option.** then
12930 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
12940 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f turns a non-zero
12950 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
12960 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
12970 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 SQLITE_CDECL sq
12980 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 lite3_config(int
12990 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
129a0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
129b0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e re database conn
129c0 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f ections.** METHO
129d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
129e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f The sqlite3_db_
129f0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
12a00 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
12a10 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ke configuration
12a20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 .** changes to a
12a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12a40 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 ction]. The int
12a50 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 erface is simila
12a60 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
12a70 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 _config()] excep
12a80 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 t that the chang
12a90 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 es apply to a si
12aa0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ngle.** [databas
12ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 e connection] (s
12ac0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
12ad0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e first argument).
12ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
12af0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
12b00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
12b10 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 D,V,...) is the
12b20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f .** [SQLITE_DBCO
12b30 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c NFIG_LOOKASIDE |
12b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 configuration v
12b50 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 erb] - an intege
12b60 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 r code .** that
12b70 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 indicates what a
12b80 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 spect of the [da
12b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12ba0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 n] is being conf
12bb0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 igured..** Subse
12bc0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 quent arguments
12bd0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
12be0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
12bf0 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 ion verb..**.**
12c00 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 ^Calls to sqlite
12c10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 3_db_config() re
12c20 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 turn SQLITE_OK i
12c30 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
12c40 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e the call is con
12c50 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 sidered successf
12c60 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul..*/.SQLITE_AP
12c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 I int SQLITE_CDE
12c80 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f CL sqlite3_db_co
12c90 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
12ca0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
12cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
12cc0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
12cd0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
12ce0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
12cf0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
12d00 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
12d10 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
12d20 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
12d30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12d40 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
12d50 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
12d60 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
12d70 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
12d80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
12d90 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
12da0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
12db0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
12dc0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
12dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
12de0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
12df0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
12e00 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
12e10 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
12e20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
12e30 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
12e40 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
12e50 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
12e60 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
12e70 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
12e80 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
12e90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
12ea0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
12eb0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
12ec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
12ed0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
12ee0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
12ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12f00 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
12f10 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
12f20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
12f30 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
12f40 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
12f50 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
12f60 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
12f70 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
12f80 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
12f90 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
12fa0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
12fb0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
12fc0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
12fd0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
12fe0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
12ff0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
13000 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
13010 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
13020 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
13030 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
13040 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
13050 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
13060 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
13070 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
13080 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
13090 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
130a0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
130b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
130c0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
130d0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
130e0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
130f0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
13100 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
13110 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
13120 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
13130 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
13140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
13150 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e oc, xRealloc, an
13160 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
13170 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
13180 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
13190 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
131a0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 ee() functions f
131b0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
131c0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e C library..** ^
131d0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
131e0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
131f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
13200 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
13210 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
13220 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
13230 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
13240 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
13250 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
13260 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
13270 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
13280 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
13290 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
132a0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
132b0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
132c0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
132d0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
132e0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
132f0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
13300 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
13310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
13320 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
13330 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
13340 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
13350 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
13360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
13370 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
13380 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
13390 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
133a0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
133b0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
133c0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
133d0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
133e0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
133f0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
13400 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
13410 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
13420 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
13430 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 ..** Every memor
13440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
13450 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 uest coming in t
13460 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f hrough [sqlite3_
13470 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 malloc()].** or
13480 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
13490 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 ()] first calls
134a0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 xRoundup. If xR
134b0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 oundup returns 0
134c0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 , .** that cause
134d0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 s the correspond
134e0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ing memory alloc
134f0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a ation to fail..*
13500 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
13510 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
13520 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
13530 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 ocator. For exa
13540 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 mple,.** it migh
13550 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 t allocate any r
13560 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f equire mutexes o
13570 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 r initialize int
13580 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 ernal data.** st
13590 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 ructures. The x
135a0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
135b0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 is invoked (indi
135c0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 rectly) by.** [s
135d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
135e0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 )] and should de
135f0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 allocate any res
13600 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a ources acquired.
13610 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 ** by xInit. Th
13620 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 e pAppData point
13630 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 er is used as th
13640 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
13650 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 to.** xInit and
13660 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a xShutdown..**.*
13670 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 * SQLite holds t
13680 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
13690 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 _STATIC_MASTER]
136a0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e mutex when it in
136b0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e vokes.** the xIn
136c0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 it method, so th
136d0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e e xInit method n
136e0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 eed not be threa
136f0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 dsafe. The.** x
13700 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
13710 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 is only called f
13720 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 rom [sqlite3_shu
13730 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 tdown()] so it d
13740 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 oes.** not need
13750 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 to be threadsafe
13760 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c either. For al
13770 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c l other methods,
13780 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 SQLite.** holds
13790 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 the [SQLITE_MUT
137a0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d EX_STATIC_MEM] m
137b0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 utex as long as
137c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
137d0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
137e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
137f0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ption is turned
13800 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 on (which.** it
13810 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 is by default) a
13820 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 nd so the method
13830 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 s are automatica
13840 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a lly serialized..
13850 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b ** However, if [
13860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
13870 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 MSTATUS] is disa
13880 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f bled, then the o
13890 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 ther.** methods
138a0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
138b0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 fe or else make
138c0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 their own arrang
138d0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 ements for.** se
138e0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a rialization..**.
138f0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ** SQLite will n
13900 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 ever invoke xIni
13910 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e t() more than on
13920 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e ce without an in
13930 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c tervening.** cal
13940 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 l to xShutdown()
13950 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
13960 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
13970 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
13980 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 mem_methods;.str
13990 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
139a0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
139b0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 *(*xMalloc)(int
139c0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 ); /* Me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
139e0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
139f0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 id (*xFree)(void
13a00 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 *); /*
13a10 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c Free a prior all
13a20 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 ocation */. voi
13a30 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 d *(*xRealloc)(v
13a40 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 oid*,int); /* R
13a50 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 esize an allocat
13a60 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
13a70 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Size)(void*);
13a80 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 /* Retur
13a90 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e n the size of an
13aa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
13ab0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 int (*xRoundup)
13ac0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 (int);
13ad0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 /* Round up requ
13ae0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f est size to allo
13af0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 cation size */.
13b00 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
13b10 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
13b20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 /* Initialize th
13b30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
13b40 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 or */. void (*x
13b50 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
13b60 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 ; /* Deinit
13b70 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
13b80 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
13b90 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
13ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
13bb0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 /* Argument to x
13bc0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 Init() and xShut
13bd0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a down() */.};../*
13be0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
13bf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
13c00 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
13c10 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 {configuration
13c20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 option}.**.** Th
13c30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
13c40 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
13c50 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
13c60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
13c70 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
13c80 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
13c90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
13ca0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
13cb0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
13cc0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
13cd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
13ce0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
13cf0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
13d00 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
13d10 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
13d20 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
13d30 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
13d40 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
13d50 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
13d60 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
13d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
13d80 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
13d90 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
13da0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
13db0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
13dc0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
13dd0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
13de0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
13df0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
13e00 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
13e10 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
13e20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
13e30 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
13e40 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
13e60 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ETHREAD]] <dt>SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
13e80 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
13e90 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
13ea0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
13eb0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
13ec0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
13ed0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
13ee0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
13ef0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
13f00 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
13f10 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
13f20 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
13f30 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
13f40 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
13f50 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
13f60 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
13f70 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
13f80 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
13f90 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
13fa0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
13fb0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
13fc0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
13fd0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
13fe0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
13ff0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
14000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
14010 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
14020 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
14030 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
14040 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
14050 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
14060 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
14070 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
14080 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
14090 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
140a0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
140b0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
140c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
140d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
140e0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
140f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
14100 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
14110 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
14120 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
14130 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
14140 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
14150 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
14160 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e to Multi-thread.
14170 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
14180 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
14190 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
141a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
141b0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
141c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
141d0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
141e0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
141f0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
14200 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
14210 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
14220 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
14230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
14240 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
14250 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
14260 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
14270 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
14280 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
14290 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
142a0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 * environment as
142b0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
142c0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 threads attempt
142d0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a to use the same.
142e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
142f0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 nection] at the
14300 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 same time. ^If
14310 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
14320 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
14330 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14340 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
14350 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
14360 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
14370 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
14380 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 ossible to set t
14390 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 he Multi-thread
143a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
143b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
143c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
143d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
143e0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
143f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
14400 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
14410 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 HREAD configurat
14420 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
14430 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14440 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
14450 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
14460 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
14470 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
14480 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
14490 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
144a0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
144b0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
144c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
144d0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e o Serialized. In
144e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
144f0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
14500 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
14510 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
14520 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
14530 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
14540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
14550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
14560 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
14570 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
14580 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
14590 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
145a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
145b0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
145c0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
145d0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
145e0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
145f0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
14600 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
14610 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
14620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
14630 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
14640 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
14650 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
14660 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
14670 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
14680 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
14690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
146a0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
146b0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
146c0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 time..** ^If SQ
146d0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
146e0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
146f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
14700 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
14710 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
14720 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
14730 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
14740 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
14750 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 Serialized [thr
14760 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
14770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
14780 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
14790 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
147a0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
147b0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
147c0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
147d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
147e0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
147f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14800 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 G_MALLOC]] <dt>S
14810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
14820 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
14830 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
14840 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 NFIG_MALLOC opti
14850 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
14860 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
14870 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 is .** a pointe
14880 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
14890 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
148a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
148b0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
148c0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
148d0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
148e0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
148f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
14900 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
14910 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
14920 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
14930 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
14940 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
14950 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
14960 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
14970 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
14980 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
14990 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
149a0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
149b0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
149c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
149d0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
149e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
149f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
14a00 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
14a10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
14a20 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
14a30 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
14a40 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 FIG_GETMALLOC op
14a50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14a60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
14a70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
14a80 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
14a90 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
14aa0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
14ab0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 tructure..** The
14ac0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
14ad0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
14ae0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
14af0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
14b00 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
14b10 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
14b20 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
14b30 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
14b40 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
14b50 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
14b60 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
14b70 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
14b80 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
14b90 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
14ba0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
14bb0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
14bc0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
14bd0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
14be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14bf0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
14c00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14c10 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
14c20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
14c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14c40 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 MSTATUS option t
14c50 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
14c60 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
14c70 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 ,.** interpreted
14c80 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 as a boolean, w
14c90 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 hich enables or
14ca0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c disables the col
14cb0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 lection of.** me
14cc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14cd0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 statistics. ^(Wh
14ce0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 en memory alloca
14cf0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
14d00 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c are.** disabled,
14d10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
14d20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
14d30 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
14d40 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
14d50 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
14d60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
14d70 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
14d80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
14d90 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
14da0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
14db0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
14dc0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
14dd0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 qlite3_status64(
14de0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a )].** </ul>)^.
14df0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ** ^Memory alloc
14e00 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
14e10 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 are enabled by
14e20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 default unless S
14e30 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 QLite is.** comp
14e40 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 iled with [SQLIT
14e50 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 E_DEFAULT_MEMSTA
14e60 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 TUS]=0 in which
14e70 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 case memory.** a
14e80 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
14e90 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
14ea0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
14eb0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
14ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
14ed0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ATCH]] <dt>SQLIT
14ee0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
14ef0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
14f00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14f10 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 _SCRATCH option
14f20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
14f30 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
14f40 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
14f50 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 can use for scra
14f60 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 tch memory. ^(T
14f70 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
14f80 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 rguments.** to S
14f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
14fa0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 ATCH: A pointer
14fb0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c an 8-byte.** al
14fc0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 igned memory buf
14fd0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 fer from which t
14fe0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 he scratch alloc
14ff0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a ations will be.*
15000 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a * drawn, the siz
15010 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 e of each scratc
15020 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a h allocation (sz
15030 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 ),.** and the ma
15040 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
15050 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
15060 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 ons (N).)^.** Th
15070 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
15080 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 must be a point
15090 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 er to an 8-byte
150a0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a aligned buffer.*
150b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a * of at least sz
150c0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
150d0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ry..** ^SQLite w
150e0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 ill not use more
150f0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 than one scratc
15100 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 h buffers per th
15110 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 read..** ^SQLite
15120 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 will never requ
15130 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 est a scratch bu
15140 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 ffer that is mor
15150 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 e than 6.** time
15160 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 s the database p
15170 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 age size..** ^If
15180 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 SQLite needs ne
15190 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a eds additional.*
151a0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
151b0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
151c0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
151d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
151e0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 ption, then .**
151f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
15200 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 )] will be used
15210 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 to obtain the me
15220 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a mory needed.<p>.
15230 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 ** ^When the app
15240 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 lication provide
15250 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 s any amount of
15260 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 scratch memory u
15270 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 sing.** SQLITE_C
15280 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 ONFIG_SCRATCH, S
15290 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e QLite avoids unn
152a0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a ecessary large.*
152b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
152c0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f c|heap allocatio
152d0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e ns]..** This can
152e0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 help [Robson pr
152f0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f oof|prevent memo
15300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
15310 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 ilures] due to h
15320 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 eap.** fragmenta
15330 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f tion in low-memo
15340 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 ry embedded syst
15350 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ems..** </dd>.**
15360 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15370 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 FIG_PAGECACHE]]
15380 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15390 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e G_PAGECACHE</dt>
153a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
153c0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 CACHE option spe
153d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
153e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a memory buffer.**
153f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
15400 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 use for the dat
15410 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 abase page cache
15420 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c with the defaul
15430 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 t page.** cache
15440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
15450 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 .** This config
15460 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e uration should n
15470 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e ot be used if an
15480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
15490 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 ine page.** cach
154a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
154b0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 is loaded using
154c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
154d0 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 FIG_PCACHE2].**
154e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
154f0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 tion..** ^There
15500 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
15510 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f nts to SQLITE_CO
15520 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 NFIG_PAGECACHE:
15530 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 A pointer to.**
15540 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 8-byte aligned.*
15550 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 * memory, the si
15560 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
15570 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 buffer (sz), and
15580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
15590 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ages (N)..** The
155a0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f sz argument sho
155b0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 uld be the size
155c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
155d0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 atabase page.**
155e0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 (a power of two
155f0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
15600 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 65536) plus some
15610 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 extra bytes for
15620 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 each.** page he
15630 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 ader. ^The numb
15640 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 er of extra byte
15650 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 s needed by the
15660 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 page header.** c
15670 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
15680 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
15690 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
156a0 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a _HDRSZ] option .
156b0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
156c0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 onfig()]..** ^It
156d0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 is harmless, ap
156e0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 art from the was
156f0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 ted memory,.** f
15700 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 or the sz parame
15710 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 ter to be larger
15720 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e than necessary.
15730 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
15740 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
15750 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
15760 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 yte aligned bloc
15770 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 k of memory that
15780 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 .** is at least
15790 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
157a0 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 mory, otherwise
157b0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
157c0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 ior is.** undefi
157d0 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ned..** ^SQLite
157e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d will use the mem
157f0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 ory provided by
15800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
15810 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 nt to satisfy it
15820 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 s.** memory need
15830 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 s for the first
15840 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 N pages that it
15850 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 adds to cache.
15860 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ^If additional.*
15870 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d * page cache mem
15880 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 ory is needed be
15890 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
158a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 vided by this op
158b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 tion, then.** SQ
158c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 Lite goes to [sq
158d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
158e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e for the addition
158f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 al storage space
15900 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15910 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
15920 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 P]] <dt>SQLITE_C
15930 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
15940 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
15950 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
15960 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
15970 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
15980 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 buffer .** that
15990 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
159a0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
159b0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 dynamic memory a
159c0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a llocation needs.
159d0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ** beyond those
159e0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 provided for by
159f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15a00 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b CRATCH] and.** [
15a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
15a20 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 GECACHE]..** ^Th
15a30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15a40 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f HEAP option is o
15a50 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
15a60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
15a70 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 led.** with eith
15a80 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
15a90 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 E_MEMSYS3] or [S
15aa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
15ab0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e SYS5] and return
15ac0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 s.** [SQLITE_ERR
15ad0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f OR] if invoked o
15ae0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 therwise..** ^Th
15af0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
15b00 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 guments to SQLIT
15b10 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a E_CONFIG_HEAP:.*
15b20 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 * An 8-byte alig
15b30 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ned pointer to t
15b40 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 he memory,.** th
15b50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
15b60 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 s in the memory
15b70 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 buffer, and the
15b80 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
15b90 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 on size..** ^If
15ba0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 the first pointe
15bb0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
15bc0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 inter) is NULL,
15bd0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 then SQLite reve
15be0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 rts.** to using
15bf0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f its default memo
15c00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 ry allocator (th
15c10 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
15c20 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e ) implementation
15c30 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e ),.** undoing an
15c40 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 y prior invocati
15c50 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f on of [SQLITE_CO
15c60 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e NFIG_MALLOC]. ^
15c70 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
15c80 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
15c90 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c NULL then the al
15ca0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
15cb0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 .** allocator is
15cc0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 engaged to hand
15cd0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 le all of SQLite
15ce0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
15cf0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 ion needs..** Th
15d00 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
15d10 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
15d20 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 ter) must be ali
15d30 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
15d40 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 e.** boundary or
15d50 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
15d60 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 vior of SQLite w
15d70 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
15d80 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d ..** The minimum
15d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
15da0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a is capped at 2*
15db0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 *12. Reasonable
15dc0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 values.** for th
15dd0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
15de0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a tion size are 2*
15df0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e *5 through 2**8.
15e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
15e20 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
15e30 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
15e40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
15e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
15e60 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 EX option takes
15e70 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
15e80 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 t which is a.**
15e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
15ea0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
15eb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
15ec0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
15ed0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
15ee0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 specifies alter
15ef0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
15f00 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
15f10 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e to be used.** in
15f20 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 place the mutex
15f30 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
15f40 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 into SQLite.)^
15f50 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 ^SQLite makes a
15f60 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
15f70 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
15f80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
15f90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 hods] structure
15fa0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 before the call
15fb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
15fc0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 onfig()] returns
15fd0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 . ^If SQLite is
15fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
15ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
16000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
16010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
16020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
16040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
16050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
16060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
16070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
16080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
16090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
160a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
160b0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 IG_MUTEX configu
160c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
160d0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
160e0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
160f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
16100 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
16110 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16120 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 NFIG_GETMUTEX</d
16130 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
16150 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 ETMUTEX option t
16160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16170 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
16180 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
16190 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
161a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
161b0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
161c0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
161d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
161e0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
161f0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
16200 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
16210 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
16220 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
16230 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
16240 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
16250 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 the default mut
16260 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ex allocation.**
16270 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
16280 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f wrapper used to
16290 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 track mutex usa
162a0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e ge for performan
162b0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 ce.** profiling
162c0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 or testing, for
162d0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 example. ^If S
162e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
162f0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
16300 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
16310 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
16320 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
16330 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
16340 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d .** the entire m
16350 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 utexing subsyste
16360 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f m is omitted fro
16370 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 m the build and
16380 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a hence calls to.*
16390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
163a0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 g()] with the SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
163c0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
163d0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
163e0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
163f0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
16400 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16410 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 FIG_LOOKASIDE]]
16420 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16430 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
16440 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
16450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
16460 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 KASIDE option ta
16470 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
16480 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
16490 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 .** the default
164a0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 size of lookasid
164b0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 e memory on each
164c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
164d0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 ction]..** The f
164e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
164f0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
16500 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
16510 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 uffer slot and t
16520 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 he second is the
16530 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
16540 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f ots allocated to
16550 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
16560 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 onnection.)^ ^(
16570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
16580 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 OKASIDE.** sets
16590 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f the <i>default</
165a0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a i> lookaside siz
165b0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 e. The [SQLITE_D
165c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
165d0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 E].** option to
165e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
165f0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 ig()] can be use
16600 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
16610 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e lookaside.** con
16620 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e figuration on in
16630 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 dividual connect
16640 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ions.)^ </dd>.**
16650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16660 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 FIG_PCACHE2]] <d
16670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16680 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
16690 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
166a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
166b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
166c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
166d0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 which is .** a p
166e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 ointer to an [sq
166f0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
16700 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
16710 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
16720 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 ifies.** the int
16730 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 erface to a cust
16740 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
16750 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a plementation.)^.
16760 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ** ^SQLite makes
16770 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
16780 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
16790 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
167a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
167b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
167c0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c CACHE2]] <dt>SQL
167d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
167e0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
167f0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
16800 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
16810 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 2 option takes a
16820 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
16830 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
16840 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 ointer to an [sq
16850 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
16860 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
16870 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 SQLite copies of
16880 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 .** the current
16890 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
168a0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 mentation into t
168b0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f hat object.)^ </
168c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
168d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 TE_CONFIG_LOG]]
168e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
168f0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 G_LOG</dt>.** <d
16900 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d> The SQLITE_CO
16910 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
16920 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 is used to confi
16930 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a gure the SQLite.
16940 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 ** global [error
16950 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 log]..** (^The
16960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
16970 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 G option takes t
16980 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 wo arguments: a
16990 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 pointer to a.**
169a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
169b0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f call signature o
169c0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c f void(*)(void*,
169d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 int,const char*)
169e0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e , .** and a poin
169f0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 ter to void. ^If
16a00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
16a10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
16a20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f L, it is.** invo
16a30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ked by [sqlite3_
16a40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 log()] to proces
16a50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 s each logging e
16a60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
16a70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 * function point
16a80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 er is NULL, the
16a90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
16aa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 interface become
16ab0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 s a no-op..** ^T
16ac0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 he void pointer
16ad0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f that is the seco
16ae0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 nd argument to S
16af0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
16b00 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 is.** passed th
16b10 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
16b20 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
16b30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
16b40 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
16b50 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 * function whene
16b60 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f ver that functio
16b70 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e n is invoked. ^
16b80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
16b90 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c eter to.** the l
16ba0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 ogger function i
16bb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
16bc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
16bd0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e to the correspon
16be0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ding.** [sqlite3
16bf0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 _log()] call and
16c00 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
16c10 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 be a [result cod
16c20 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 e] or an.** [ext
16c30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
16c40 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 e]. ^The third
16c50 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
16c60 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 to the logger i
16c70 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 s.** log message
16c80 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e after formattin
16c90 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 g via [sqlite3_s
16ca0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 nprintf()]..** T
16cb0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e he SQLite loggin
16cc0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e g interface is n
16cd0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 ot reentrant; th
16ce0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
16cf0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 n.** supplied by
16d00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
16d10 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 must not invoke
16d20 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
16d30 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d rface..** In a m
16d40 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
16d50 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 plication, the a
16d60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
16d70 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
16d80 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 ction must be th
16d90 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a readsafe. </dd>.
16da0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16db0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e ONFIG_URI]] <dt>
16dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
16dd0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 I.** <dd>^(The S
16de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
16df0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
16e00 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
16e10 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 of type int..**
16e20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 If non-zero, the
16e30 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 n URI handling i
16e40 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c s globally enabl
16e50 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d ed. If the param
16e60 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a eter is zero,.**
16e70 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
16e80 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 ng is globally d
16e90 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 isabled.)^ ^If U
16ea0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
16eb0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c lobally.** enabl
16ec0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 ed, all filename
16ed0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
16ee0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
16ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
16f00 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f ],.** [sqlite3_o
16f10 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 pen16()] or.** s
16f20 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
16f30 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d of [ATTACH] com
16f40 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 mands are interp
16f50 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 reted as URIs, r
16f60 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 egardless.** of
16f70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
16f80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
16f90 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 URI] flag is set
16fa0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
16fb0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
16fc0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 is opened. ^If
16fd0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 it is globally d
16fe0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d isabled, filenam
16ff0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 es are.** only i
17000 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
17010 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 Is if the SQLITE
17020 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 _OPEN_URI flag i
17030 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a s set when the.*
17040 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
17050 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
17060 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 ^(By default, U
17070 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
17080 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
17090 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
170a0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
170b0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
170c0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
170d0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
170e0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 symbol defined.)
170f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
17100 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
17110 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 _INDEX_SCAN]] <d
17120 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17130 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
17140 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 CAN.** <dd>^The
17150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
17160 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
17170 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 N option takes a
17180 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a single integer.
17190 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 ** argument whic
171a0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
171b0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e as a boolean in
171c0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 order to enable
171d0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 or disable.** t
171e0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
171f0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 ng indices for f
17200 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 ull table scans
17210 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 in the query opt
17220 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 imizer..** ^The
17230 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
17240 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a is determined.**
17250 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
17260 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 ALLOW_COVERING_I
17270 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 NDEX_SCAN] compi
17280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
17290 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 or is "on".** if
172a0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 that compile-ti
172b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 me option is omi
172c0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 tted..** The abi
172d0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 lity to disable
172e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 the use of cover
172f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 ing indices for
17300 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 full table scans
17310 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 .** is because s
17320 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ome incorrectly
17330 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 coded legacy app
17340 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lications might
17350 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 malfunction.** w
17360 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 hen the optimiza
17370 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
17380 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 Providing the
17390 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 ability to.** di
173a0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 sable the optimi
173b0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 zation allows th
173c0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 e older, buggy a
173d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
173e0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f to work.** witho
173f0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 ut change even w
17400 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f ith newer versio
17410 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
17420 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
17430 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 FIG_PCACHE]] [[S
17440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
17450 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e PCACHE]].** <dt>
17460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
17470 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f ACHE and SQLITE_
17480 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
17490 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f .** <dd> These o
174a0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c ptions are obsol
174b0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e ete and should n
174c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 ot be used by ne
174d0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 w code..** They
174e0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
174f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
17500 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 tibility but are
17510 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 now no-ops..**
17520 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
17530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
17540 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 OG]].** <dt>SQLI
17550 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
17560 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
17570 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
17580 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 lable if sqlite
17590 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
175a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
175b0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 ENABLE_SQLLOG] p
175c0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 re-processor mac
175d0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 ro defined. The
175e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 first argument s
175f0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f hould.** be a po
17600 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 inter to a funct
17610 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 ion of type void
17620 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
17630 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 3*,const char*,
17640 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 int)..** The sec
17650 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 ond should be of
17660 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 type (void*). T
17670 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
17680 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 nvoked by the li
17690 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 brary.** in thre
176a0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 e separate circu
176b0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 mstances, identi
176c0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 fied by the valu
176d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a e passed as the.
176e0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
176f0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 ter. If the four
17700 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
17710 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 0, then the data
17720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
17730 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
17740 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
17750 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f has just been o
17760 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 pened. The third
17770 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 argument.** poi
17780 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 nts to a buffer
17790 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
177a0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 ame of the main
177b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 database file. I
177c0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 f the.** fourth
177d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 parameter is 1,
177e0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 then the SQL sta
177f0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 tement that the
17800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a third parameter.
17810 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 ** points to has
17820 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 just been execu
17830 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 ted. Or, if the
17840 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
17850 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 is 2, then.** t
17860 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 he connection be
17870 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 ing passed as th
17880 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
17890 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 er is being clos
178a0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 ed. The.** third
178b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 parameter is pa
178c0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 ssed NULL In thi
178d0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d s case. An exam
178e0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ple of using thi
178f0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 s.** configurati
17900 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 on option can be
17910 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 seen in the "te
17920 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 st_sqllog.c" sou
17930 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 rce file in.** t
17940 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c he canonical SQL
17950 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e ite source tree.
17960 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
17970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
17980 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 _SIZE]].** <dt>S
17990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
179a0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 P_SIZE.** <dd>^S
179b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
179c0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f P_SIZE takes two
179d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
179e0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 (sqlite3_int64)
179f0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 values.** that a
17a00 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d re the default m
17a10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 map size limit (
17a20 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 the default sett
17a30 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 ing for.** [PRAG
17a40 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 MA mmap_size]) a
17a50 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 nd the maximum a
17a60 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
17a70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 limit..** ^The
17a80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
17a90 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
17aa0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 n by each databa
17ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 se connection us
17ac0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 ing.** either th
17ad0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 e [PRAGMA mmap_s
17ae0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 ize] command, or
17af0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a by using the.**
17b00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [SQLITE_FCNTL_M
17b10 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 MAP_SIZE] file c
17b20 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d ontrol. ^(The m
17b30 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d aximum allowed m
17b40 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c map size.** will
17b50 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 be silently tru
17b60 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 ncated if necess
17b70 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 ary so that it d
17b80 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 oes not exceed t
17b90 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 he.** compile-ti
17ba0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 me maximum mmap
17bb0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a size set by the.
17bc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d ** [SQLITE_MAX_M
17bd0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c MAP_SIZE] compil
17be0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e e-time option.)^
17bf0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 .** ^If either a
17c00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
17c10 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 option is negati
17c20 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 ve, then that ar
17c30 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 gument is.** cha
17c40 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 nged to its comp
17c50 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 ile-time default
17c60 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
17c70 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
17c80 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e APSIZE]].** <dt>
17c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
17ca0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 N32_HEAPSIZE.**
17cb0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
17cc0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
17cd0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 PSIZE option is
17ce0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
17cf0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 f SQLite is.** c
17d00 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 ompiled for Wind
17d10 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 ows with the [SQ
17d20 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f LITE_WIN32_MALLO
17d30 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 C] pre-processor
17d40 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 macro.** define
17d50 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 d. ^SQLITE_CONFI
17d60 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
17d70 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 takes a 32-bit
17d80 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
17d90 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 value.** that s
17da0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 pecifies the max
17db0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 imum size of the
17dc0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a created heap..*
17dd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
17de0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
17df0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 Z]].** <dt>SQLIT
17e00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
17e10 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 HDRSZ.** <dd>^Th
17e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17e30 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 PCACHE_HDRSZ opt
17e40 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
17e50 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
17e60 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
17e70 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
17e80 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f and writes into
17e90 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 that integer th
17ea0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
17eb0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 a.** bytes per p
17ec0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 age required for
17ed0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 each page in [S
17ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
17ef0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 ECACHE]..** The
17f00 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 amount of extra
17f10 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 space required c
17f20 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 an change depend
17f30 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 ing on the compi
17f40 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 ler,.** target p
17f50 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c latform, and SQL
17f60 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a ite version..**.
17f70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
17f80 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 IG_PMASZ]].** <d
17f90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17fa0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 PMASZ.** <dd>^Th
17fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17fc0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b PMASZ option tak
17fd0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 es a single para
17fe0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 meter which.** i
17ff0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e s an unsigned in
18000 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 teger and sets t
18010 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 he "Minimum PMA
18020 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 Size" for the mu
18030 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 ltithreaded.** s
18040 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e orter to that in
18050 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 teger. The defa
18060 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 ult minimum PMA
18070 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 Size is set by t
18080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f he.** [SQLITE_SO
18090 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 RTER_PMASZ] comp
180a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
180b0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 New threads ar
180c0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f e launched.** to
180d0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 help with sort
180e0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 operations when
180f0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f multithreaded so
18100 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 rting.** is enab
18110 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b led (using the [
18120 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 PRAGMA threads]
18130 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 command) and the
18140 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 amount of conte
18150 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 nt.** to be sort
18160 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 ed exceeds the p
18170 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 age size times t
18180 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 he minimum of th
18190 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 e.** [PRAGMA cac
181a0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 he_size] setting
181b0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e and this value.
181c0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
181d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
181e0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
181f0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 1 /* nil */.#d
18200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18210 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
18220 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 2 /* nil */.#
18230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18240 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 NFIG_SERIALIZED
18250 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 3 /* nil */.
18260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18270 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 ONFIG_MALLOC
18280 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 4 /* sqlite
18290 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
182a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
182b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
182c0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 C 5 /* sqli
182d0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
182e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
182f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
18300 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f H 6 /* vo
18310 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
18320 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
18330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
18340 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 CACHE 7 /*
18350 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
18360 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
18370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
18380 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f AP 8 /
18390 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 * void*, int nBy
183a0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 te, int min */.#
183b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
183c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 NFIG_MEMSTATUS
183d0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 9 /* boolean
183e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
183f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
18400 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 10 /* sq
18410 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
18420 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
18430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
18440 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f TMUTEX 11 /
18450 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
18460 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 methods* */./* p
18470 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 reviously SQLITE
18480 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c _CONFIG_CHUNKALL
18490 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e OC 12 which is n
184a0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 ow unused. */ .#
184b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
184c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
184d0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 13 /* int int
184e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
184f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
18500 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 14 /* no
18510 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 -op */.#define S
18520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
18530 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a PCACHE 15 /*
18540 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
18550 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18560 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 LOG 16
18570 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a /* xFunc, void*
18580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18590 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 TE_CONFIG_URI
185a0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 17 /* in
185b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
185c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
185d0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 E2 18 /* s
185e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
185f0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 thods2* */.#defi
18600 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18610 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 _GETPCACHE2 19
18620 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
18630 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
18640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18650 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
18660 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f INDEX_SCAN 20 /
18670 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
18680 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18690 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 QLLOG 21
186a0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 /* xSqllog, void
186b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
186c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
186d0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 SIZE 22 /* s
186e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 qlite3_int64, sq
186f0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 lite3_int64 */.#
18700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18710 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
18720 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 IZE 23 /*
18730 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 int nByte */.#de
18740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18750 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
18760 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 24 /* in
18770 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e t *psz */.#defin
18780 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18790 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 PMASZ
187a0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 25 /* unsig
187b0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f ned int szPma */
187c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
187d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
187e0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 ction Configurat
187f0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a ion Options.**.*
18800 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
18810 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
18820 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
18830 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
18840 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
18850 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
18860 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
18870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 o the [sqlite3_d
18880 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
18890 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
188a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
188b0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
188c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
188d0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
188e0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
188f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
18900 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
18910 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
18920 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
18930 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
18940 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
18950 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
18960 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
18970 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
18980 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 l worked. ^The
18990 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
189a0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
189b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
189c0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
189d0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
189e0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
189f0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
18a00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
18a10 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
18a20 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
18a30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
18a40 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
18a50 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
18a60 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 n takes three ad
18a70 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
18a80 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
18a90 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 e the .** [looka
18aa0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
18ab0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 cator] configura
18ac0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 tion for the [da
18ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18ae0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 n]..** ^The firs
18af0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 t argument (the
18b00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
18b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
18b20 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a onfig()] is a.**
18b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
18b40 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 mory buffer to u
18b50 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 se for lookaside
18b60 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 memory..** ^The
18b70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
18b80 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 after the SQLITE
18b90 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
18ba0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 IDE verb.** may
18bb0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 be NULL in which
18bc0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c case SQLite wil
18bd0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a l allocate the.*
18be0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 * lookaside buff
18bf0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 er itself using
18c00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18c10 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 )]. ^The second
18c20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
18c30 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
18c40 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
18c50 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 slot. ^The thi
18c60 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
18c70 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
18c80 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 slots. The size
18c90 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 of the buffer i
18ca0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
18cb0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 ment must be gre
18cc0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 ater than.** or
18cd0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f equal to the pro
18ce0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f duct of the seco
18cf0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 nd and third arg
18d00 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 uments. The buf
18d10 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 fer.** must be a
18d20 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
18d30 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e yte boundary. ^
18d40 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 If the second ar
18d50 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c gument to.** SQL
18d60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
18d70 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 KASIDE is not a
18d80 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 multiple of 8, i
18d90 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a t is internally.
18da0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 ** rounded down
18db0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c to the next smal
18dc0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 ler multiple of
18dd0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 8. ^(The lookas
18de0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f ide memory.** co
18df0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
18e00 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
18e10 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 ction can only b
18e20 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 e changed when t
18e30 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f hat.** connectio
18e40 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 n is not current
18e50 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 ly using lookasi
18e60 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e de memory, or in
18e70 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 other words.**
18e80 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e when the "curren
18e90 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 t value" returne
18ea0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
18eb0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 _db_status](D,[S
18ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
18ed0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 KASIDE],...) is
18ee0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 zero..** Any att
18ef0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 empt to change t
18f00 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d he lookaside mem
18f10 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ory configuratio
18f20 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 n when lookaside
18f30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e .** memory is in
18f40 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 use leaves the
18f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e configuration un
18f60 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
18f70 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rns .** [SQLITE_
18f80 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a BUSY].)^</dd>.**
18f90 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
18fa0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
18fb0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e KEY</dt>.** <dd>
18fc0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
18fd0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
18fe0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 or disable the e
18ff0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a nforcement of.**
19000 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f [foreign key co
19010 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 nstraints]. The
19020 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
19030 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
19040 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
19050 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
19060 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
19070 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
19080 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c FK enforcement,
19090 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 .** positive to
190a0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 enable FK enforc
190b0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 ement or negativ
190c0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e e to leave FK en
190d0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 forcement.** unc
190e0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 hanged. The sec
190f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
19100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
19110 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
19120 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
19130 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
19140 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 cate whether FK
19150 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f enforcement is o
19160 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c ff or on.** foll
19170 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
19180 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
19190 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
191a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
191b0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
191c0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e he FK enforcemen
191d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 t setting is not
191e0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
191f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
19200 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19210 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f ENABLE_TRIGGER</
19220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
19230 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
19240 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
19250 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 sable [CREATE TR
19260 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 IGGER | triggers
19270 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 ]..** There shou
19280 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
19290 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
192a0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
192b0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
192c0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
192d0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 o disable trigge
192e0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 rs,.** positive
192f0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 to enable trigge
19300 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 rs or negative t
19310 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
19320 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
19330 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
19340 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
19350 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
19360 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
19370 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
19380 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
19390 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 ether triggers a
193a0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 re disabled or e
193b0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nabled.** follow
193c0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
193d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
193e0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
193f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
19400 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
19410 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 trigger setting
19420 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
19430 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
19440 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
19450 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
19460 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
19470 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 1001 /* voi
19480 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 d* int int */.#d
19490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
194a0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
194b0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 Y 1002 /* i
194c0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
194d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
194e0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
194f0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 R 1003 /* int
19500 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int* */.../*.**
19510 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
19520 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
19530 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
19540 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
19550 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
19560 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
19570 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
19580 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
19590 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
195a0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
195b0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
195c0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
195d0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
195e0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
195f0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
19600 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
19610 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
19620 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
19630 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
19640 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e LL sqlite3_exten
19650 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
19660 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
19670 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 noff);../*.** CA
19680 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 PI3REF: Last Ins
19690 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 ert Rowid.** MET
196a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
196b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 ** ^Each entry i
196c0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 n most SQLite ta
196d0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 bles (except for
196e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d [WITHOUT ROWID]
196f0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 tables).** has
19700 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 a unique 64-bit
19710 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 signed.** intege
19720 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 r key called the
19730 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 [ROWID | "rowid
19740 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 "]. ^The rowid i
19750 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 s always availab
19760 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 le.** as an unde
19770 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 clared column na
19780 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 med ROWID, OID,
19790 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f or _ROWID_ as lo
197a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e ng as those.** n
197b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 ames are not als
197c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 o used by explic
197d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f itly declared co
197e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 lumns. ^If.** th
197f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
19800 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e lumn of type [IN
19810 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
19820 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c Y] then that col
19830 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 umn.** is anothe
19840 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 r alias for the
19850 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rowid..**.** ^Th
19860 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 e sqlite3_last_i
19870 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 nsert_rowid(D) i
19880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
19890 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
198a0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the .** most rec
198b0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b ent successful [
198c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 INSERT] into a r
198d0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 owid table or [v
198e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
198f0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e on database con
19900 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 nection D..** ^I
19910 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 nserts into [WIT
19920 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c HOUT ROWID] tabl
19930 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 es are not recor
19940 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 ded..** ^If no s
19950 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
19960 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 T]s into rowid t
19970 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 ables.** have ev
19980 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 er occurred on t
19990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
199a0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 ection D, .** th
199b0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f en sqlite3_last_
199c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 insert_rowid(D)
199d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
199e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 .** ^(If an [INS
199f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 ERT] occurs with
19a00 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 in a trigger or
19a10 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 within a [virtua
19a20 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 l table].** meth
19a30 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f od, then this ro
19a40 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 utine will retur
19a50 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 n the [rowid] of
19a60 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a the inserted.**
19a70 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 row as long as
19a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
19a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 irtual table met
19aa0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a hod is running..
19ab0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 ** But once the
19ac0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
19ad0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
19ae0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 ends, the value
19af0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 returned .** by
19b00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 this routine rev
19b10 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 erts to what it
19b20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 was before the t
19b30 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
19b40 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f l.** table metho
19b50 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a d began.)^.**.**
19b60 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 ^An [INSERT] th
19b70 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
19b80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
19b90 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
19ba0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
19bb0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 NSERT] and does
19bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
19bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
19be0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
19bf0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 . ^Thus INSERT
19c00 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
19c10 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
19c20 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
19c30 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
19c40 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
19c50 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
19c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
19c70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
19c80 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
19c90 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e n fails. ^(When
19ca0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
19cb0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 CE.** encounters
19cc0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
19cd0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 olation, it does
19ce0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a not fail. The.
19cf0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e ** INSERT contin
19d00 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
19d10 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 n after deleting
19d20 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 rows that cause
19d30 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 d.** the constra
19d40 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 int problem so I
19d50 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
19d60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 will always cha
19d70 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 nge.** the retur
19d80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
19d90 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a interface.)^.**.
19da0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 ** ^For the purp
19db0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 oses of this rou
19dc0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 tine, an [INSERT
19dd0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 ] is considered
19de0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 to.** be success
19df0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 ful even if it i
19e00 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 s subsequently r
19e10 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
19e20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
19e30 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f is accessible to
19e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
19e50 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 via the.** [last
19e60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 _insert_rowid()
19e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
19e80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
19e90 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
19ea0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
19eb0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
19ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
19ed0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b tion while the [
19ee0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
19ef0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 ert_rowid()].**
19f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
19f10 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
19f20 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
19f30 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
19f40 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
19f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
19f60 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
19f70 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 _rowid()] is.**
19f80 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
19f90 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 d might not equa
19fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 l either the old
19fb0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c or the new.** l
19fc0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
19fd0 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 d]..*/.SQLITE_AP
19fe0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
19ff0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1a000 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
1a010 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
1a020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1a030 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
1a040 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
1a050 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 dified.** METHOD
1a060 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1a070 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
1a080 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
1a090 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
1a0a0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a ed, inserted or.
1a0b0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 ** deleted by th
1a0c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
1a0d0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
1a0e0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
1a0f0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
1a100 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
1a110 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 connection speci
1a120 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 fied by the only
1a130 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
1a140 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 Executing any ot
1a150 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 her type of SQL
1a160 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
1a170 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 ot modify the va
1a180 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1a190 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
1a1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 ..**.** ^Only ch
1a1b0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 anges made direc
1a1c0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 tly by the INSER
1a1d0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
1a1e0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 ETE statement ar
1a1f0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
1a200 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e - auxiliary chan
1a210 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 ges caused by [C
1a220 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
1a230 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b triggers], .** [
1a240 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
1a250 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 ons] or [REPLACE
1a260 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 ] constraint res
1a270 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 olution are not
1a280 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 counted..** .**
1a290 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
1a2a0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 w that are inter
1a2b0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 cepted by .** [I
1a2c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
1a2d0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 r | INSTEAD OF t
1a2e0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 riggers] are not
1a2f0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 counted. ^The v
1a300 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 alue .** returne
1a310 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
1a320 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 nges() immediate
1a330 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 ly after an INSE
1a340 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a RT, UPDATE or .*
1a350 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 * DELETE stateme
1a360 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 nt run on a view
1a370 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e is always zero.
1a380 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 Only changes ma
1a390 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 de to real .** t
1a3a0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 ables are counte
1a3b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 d..**.** Things
1a3c0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 are more complic
1a3d0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 ated if the sqli
1a3e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
1a3f0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 nction is.** exe
1a400 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 cuted while a tr
1a410 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 igger program is
1a420 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d running. This m
1a430 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 ay happen if the
1a440 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 .** program uses
1a450 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 the [changes()
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f SQL function], o
1a470 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 r if some other
1a480 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
1a490 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c tion invokes sql
1a4a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 ite3_changes() d
1a4b0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 irectly. Essenti
1a4c0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c ally:.** .** <ul
1a4d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 >.** <li> ^(Be
1a4e0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 fore entering a
1a4f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
1a500 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1a510 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
1a520 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1a530 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 ) function is sa
1a540 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 ved. After the t
1a550 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a rigger program .
1a560 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 ** has fi
1a570 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 nished, the orig
1a580 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 inal value is re
1a590 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a stored.)^.** .**
1a5a0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e <li> ^(Within
1a5b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
1a5c0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 am each INSERT,
1a5d0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 UPDATE and DELET
1a5e0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 E .** sta
1a5f0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 tement sets the
1a600 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1a610 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 y sqlite3_change
1a620 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 s() .** u
1a630 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 pon completion a
1a640 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 s normal. Of cou
1a650 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 rse, this value
1a660 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 will not include
1a670 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 .** any
1a680 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 changes performe
1a690 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 d by sub-trigger
1a6a0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 s, as the sqlite
1a6b0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 3_changes() .**
1a6c0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c value wil
1a6d0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 l be saved and r
1a6e0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 estored after ea
1a6f0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 ch sub-trigger h
1a700 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 as run.)^.** </u
1a710 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 l>.** .** ^This
1a720 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 means that if th
1a730 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 e changes() SQL
1a740 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d function (or sim
1a750 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a ilar) is used.**
1a760 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e by the first IN
1a770 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1a780 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
1a790 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
1a7a0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e r, it .** return
1a7b0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 s the value as s
1a7c0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c et when the call
1a7d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 ing statement be
1a7e0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a gan executing..*
1a7f0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 * ^If it is used
1a800 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f by the second o
1a810 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 r subsequent suc
1a820 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 h statement with
1a830 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a in a trigger .**
1a840 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 program, the va
1a850 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 lue returned ref
1a860 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 lects the number
1a870 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
1a880 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 d by the .** pre
1a890 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 vious INSERT, UP
1a8a0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
1a8b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
1a8c0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
1a8d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1a8e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
1a8f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
1a900 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
1a910 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
1a920 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
1a930 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
1a940 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
1a950 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
1a960 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
1a970 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
1a980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a990 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
1a9a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
1a9b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
1a9c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1a9d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
1a9e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
1a9f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 meaningful..*/.S
1aa00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
1aa10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1aa20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
1aa30 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1aa40 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
1aa50 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
1aa60 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 dified.** METHOD
1aa70 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1aa80 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
1aa90 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c eturns the total
1aaa0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
1aab0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 inserted, modifi
1aac0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 ed or.** deleted
1aad0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d by all [INSERT]
1aae0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 , [UPDATE] or [D
1aaf0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
1ab00 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 s completed.** s
1ab10 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 ince the databas
1ab20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 e connection was
1ab30 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 opened, includi
1ab40 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 ng those execute
1ab50 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 d as.** part of
1ab60 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 trigger programs
1ab70 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 . ^Executing any
1ab80 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
1ab90 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL statement.**
1aba0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 does not affect
1abb0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1abc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f ed by sqlite3_to
1abd0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a tal_changes()..*
1abe0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d * .** ^Changes m
1abf0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b ade as part of [
1ac00 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
1ac10 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 ons] are include
1ac20 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e d in the.** coun
1ac30 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 t, but those mad
1ac40 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 e as part of REP
1ac50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 LACE constraint
1ac60 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a resolution are.*
1ac70 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 * not. ^Changes
1ac80 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 to a view that a
1ac90 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 re intercepted b
1aca0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 y INSTEAD OF tri
1acb0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f ggers .** are no
1acc0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a t counted..** .*
1acd0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
1ace0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1acf0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 )] interface, th
1ad00 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e e.** [count_chan
1ad10 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 ges pragma], and
1ad20 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e the [total_chan
1ad30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
1ad40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
1ad50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
1ad60 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
1ad70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
1ad80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
1ad90 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
1ada0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
1adb0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
1adc0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
1add0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
1ade0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
1adf0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 meaningful..*/.S
1ae00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
1ae10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1ae20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1ae30 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
1ae40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
1ae50 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
1ae60 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a Running Query.**
1ae70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1ae80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1ae90 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
1aea0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
1aeb0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
1aec0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
1aed0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
1aee0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
1aef0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
1af00 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
1af10 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
1af20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
1af30 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
1af40 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
1af50 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
1af60 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
1af70 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
1af80 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
1af90 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
1afa0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f * ^It is safe to
1afb0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
1afc0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
1afd0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
1afe0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
1aff0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
1b000 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
1b010 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
1b020 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
1b030 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
1b040 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
1b050 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
1b060 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
1b070 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
1b080 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
1b090 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1b0a0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
1b0b0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f .** ^If an SQL o
1b0c0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 peration is very
1b0d0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 nearly finished
1b0e0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
1b0f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 n.** sqlite3_int
1b100 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c errupt() is call
1b110 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 ed, then it migh
1b120 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 t not have an op
1b130 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 portunity.** to
1b140 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 be interrupted a
1b150 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 nd might continu
1b160 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e e to completion.
1b170 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f .**.** ^An SQL o
1b180 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
1b190 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
1b1a0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
1b1b0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
1b1c0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 ^If the interrup
1b1d0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ted SQL operatio
1b1e0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 n is an INSERT,
1b1f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
1b200 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 E.** that is ins
1b210 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 ide an explicit
1b220 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
1b230 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 n the entire tra
1b240 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c nsaction.** will
1b250 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
1b260 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a automatically..*
1b270 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1b280 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 3_interrupt(D) c
1b290 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 all is in effect
1b2a0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 until all curre
1b2b0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 ntly running.**
1b2c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f SQL statements o
1b2d0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
1b2e0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 ection] D comple
1b2f0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 te. ^Any new SQ
1b300 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1b310 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1b320 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
1b330 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
1b340 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 all and before t
1b350 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 he .** running s
1b360 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 tatements reache
1b370 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 s zero are inter
1b380 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 rupted as if the
1b390 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 y had been.** ru
1b3a0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 nning prior to t
1b3b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1b3c0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e rupt() call. ^N
1b3d0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
1b3e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
1b3f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
1b400 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
1b410 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 t count reaches
1b420 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 zero are.** not
1b430 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 effected by the
1b440 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1b450 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 t()..** ^A call
1b460 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 to sqlite3_inter
1b470 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 rupt(D) that occ
1b480 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 urs when there a
1b490 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a re no running.**
1b4a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1b4b0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 is a no-op and h
1b4c0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
1b4d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1b4e0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
1b4f0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
1b500 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b510 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a call returns..*
1b520 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
1b530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b540 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 closes while [sq
1b550 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1b560 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 )].** is running
1b570 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 then bad things
1b580 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 will likely hap
1b590 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
1b5a0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 PI void SQLITE_S
1b5b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69 TDCALL sqlite3_i
1b5c0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 nterrupt(sqlite3
1b5d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1b5e0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
1b5f0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
1b600 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a nt Is Complete.*
1b610 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b620 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 nes are useful d
1b630 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 uring command-li
1b640 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
1b650 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
1b660 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
1b670 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 d text seems to
1b680 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 form a complete
1b690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 SQL statement or
1b6a0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 .** if additiona
1b6b0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 l input is neede
1b6c0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 d before sending
1b6d0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a the text into.*
1b6e0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 * SQLite for par
1b6f0 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f sing. ^These ro
1b700 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
1b710 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
1b720 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
1b730 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
1b740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
1b750 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ^A statement is
1b760 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 judged to be.**
1b770 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 complete if it e
1b780 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 nds with a semic
1b790 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 olon token and i
1b7a0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f s not a prefix o
1b7b0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d f a.** well-form
1b7c0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ed CREATE TRIGGE
1b7d0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 R statement. ^S
1b7e0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
1b7f0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
1b800 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
1b810 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
1b820 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
1b830 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
1b840 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
1b850 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
1b860 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
1b870 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
1b880 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
1b890 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
1b8a0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
1b8b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
1b8c0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 nator. ^Whitesp
1b8d0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 ace.** and comme
1b8e0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 nts that follow
1b8f0 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f the final semico
1b900 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e lon are ignored.
1b910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1b920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 utines return 0
1b930 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
1b940 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 is incomplete.
1b950 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 ^If a.** memory
1b960 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
1b970 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e s, then SQLITE_N
1b980 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 OMEM is returned
1b990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
1b9a0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
1b9b0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
1b9c0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
1b9d0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
1b9e0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
1b9f0 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
1ba00 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 ** ^(If SQLite h
1ba10 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
1ba20 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
1ba30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
1ba40 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
1ba50 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
1ba60 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
1ba70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
1ba80 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
1ba90 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
1baa0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
1bab0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
1bac0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
1bad0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
1bae0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
1baf0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
1bb00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1bb10 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
1bb20 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
1bb30 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
1bb40 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
1bb50 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a is complete.)^.*
1bb60 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
1bb70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
1bb80 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
1bb90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1bba0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
1bbb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ..**.** The inpu
1bbc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
1bbd0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
1bbe0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
1bbf0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
1bc00 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
1bc10 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a byte order..*/.
1bc20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
1bc30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1bc40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 lite3_complete(c
1bc50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b onst char *sql);
1bc60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1bc70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1bc80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1bc90 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
1bca0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1bcb0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
1bcc0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
1bcd0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
1bce0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 rrors.** KEYWORD
1bcf0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 S: {busy-handler
1bd00 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 callback} {busy
1bd10 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 handler}.** MET
1bd20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1bd30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1bd40 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 busy_handler(D,X
1bd50 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 ,P) routine sets
1bd60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1bd70 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d tion X.** that m
1bd80 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
1bd90 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 with argument P
1bda0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 whenever.** an a
1bdb0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 ttempt is made t
1bdc0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 o access a datab
1bdd0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 ase table associ
1bde0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 ated with.** [da
1bdf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1be00 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 n] D when anothe
1be10 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 r thread.** or p
1be20 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 rocess has the t
1be30 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 able locked..**
1be40 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 The sqlite3_busy
1be50 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 _handler() inter
1be60 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
1be70 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 implement.** [sq
1be80 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1be90 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d ut()] and [PRAGM
1bea0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e A busy_timeout].
1beb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 .**.** ^If the b
1bec0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
1bed0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 NULL, then [SQLI
1bee0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 TE_BUSY].** is r
1bef0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
1bf00 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 ely upon encount
1bf10 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 ering the lock.
1bf20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
1bf30 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 llback.** is not
1bf40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
1bf50 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 callback might b
1bf60 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
1bf70 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a wo arguments..**
1bf80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
1bf90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 rgument to the b
1bfa0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 usy handler is a
1bfb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 copy of the voi
1bfc0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 d* pointer which
1bfd0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 .** is the third
1bfe0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
1bff0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1c000 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e r(). ^The secon
1c010 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
1c020 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1c030 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
1c040 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
1c050 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
1c060 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
1c070 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 een invoked prev
1c080 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 iously for the s
1c090 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e ame locking even
1c0a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 t. ^If the.** b
1c0b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 usy callback ret
1c0c0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 urns 0, then no
1c0d0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d additional attem
1c0e0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a pts are made to.
1c0f0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 ** access the da
1c100 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 tabase and [SQLI
1c110 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 TE_BUSY] is retu
1c120 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 rned.** to the a
1c130 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e pplication..** ^
1c140 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
1c150 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
1c160 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 , then another a
1c170 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 ttempt.** is mad
1c180 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 e to access the
1c190 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 database and the
1c1a0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a cycle repeats..
1c1b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e **.** The presen
1c1c0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e ce of a busy han
1c1d0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 dler does not gu
1c1e0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 arantee that it
1c1f0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a will be invoked.
1c200 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 ** when there is
1c210 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e lock contention
1c220 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 . ^If SQLite det
1c230 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 ermines that inv
1c240 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a oking the busy.*
1c250 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 * handler could
1c260 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 result in a dead
1c270 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f lock, it will go
1c280 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 ahead and retur
1c290 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1c2a0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ** to the applic
1c2b0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 ation instead of
1c2c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a invoking the .*
1c2d0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a * busy handler..
1c2e0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 ** Consider a sc
1c2f0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 enario where one
1c300 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1c310 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 ing a read lock
1c320 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 that.** it is tr
1c330 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 ying to promote
1c340 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f to a reserved lo
1c350 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f ck and.** a seco
1c360 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f nd process is ho
1c370 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 lding a reserved
1c380 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 lock that it is
1c390 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 trying.** to pr
1c3a0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c omote to an excl
1c3b0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 usive lock. The
1c3c0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 first process c
1c3d0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a annot proceed.**
1c3e0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1c3f0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 locked by the se
1c400 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 cond and the sec
1c410 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e ond process cann
1c420 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 ot.** proceed be
1c430 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
1c440 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ked by the first
1c450 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 . If both proce
1c460 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 sses.** invoke t
1c470 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 he busy handlers
1c480 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d , neither will m
1c490 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 ake any progress
1c4a0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a . Therefore,.**
1c4b0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 SQLite returns
1c4c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f [SQLITE_BUSY] fo
1c4d0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 r the first proc
1c4e0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 ess, hoping that
1c4f0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e this.** will in
1c500 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 duce the first p
1c510 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 rocess to releas
1c520 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 e its read lock
1c530 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 and allow.** the
1c540 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1c550 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a to proceed..**.*
1c560 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
1c570 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
1c580 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 NULL..**.** ^(Th
1c590 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
1c5a0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
1c5b0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f ndler defined fo
1c5c0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 r each.** [datab
1c5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
1c5e0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 Setting a new
1c5f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 busy handler cle
1c600 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 ars any.** previ
1c610 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 ously set handle
1c620 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 r.)^ ^Note that
1c630 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
1c640 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
1c650 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 ].** or evaluati
1c660 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f ng [PRAGMA busy_
1c670 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 timeout=N] will
1c680 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 change the.** bu
1c690 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 sy handler and t
1c6a0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 hus clear any pr
1c6b0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 eviously set bus
1c6c0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a y handler..**.**
1c6d0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 The busy callba
1c6e0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 ck should not ta
1c6f0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 ke any actions w
1c700 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a hich modify the.
1c710 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1c720 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1c730 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
1c740 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 dler. In other
1c750 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 words,.** the bu
1c760 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f sy handler is no
1c770 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e t reentrant. An
1c780 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
1c790 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
1c7a0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
1c7b0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 ** .** A busy ha
1c7c0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 ndler must not c
1c7d0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
1c7e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1c7f0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 or [prepared sta
1c800 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 tement] that inv
1c810 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
1c820 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ndler..*/.SQLITE
1c830 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
1c840 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1c850 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
1c860 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f ite3*, int(*)(vo
1c870 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 id*,int), void*)
1c880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c890 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 F: Set A Busy Ti
1c8a0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a meout.** METHOD:
1c8b0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1c8c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
1c8d0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
1c8e0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
1c8f0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 handler] that s
1c900 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 leeps.** for a s
1c910 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 pecified amount
1c920 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 of time when a t
1c930 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
1c940 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a ^The handler.**
1c950 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 will sleep mult
1c960 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c iple times until
1c970 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1c980 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1c990 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 leeping.** have
1c9a0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 accumulated. ^A
1c9b0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d fter at least "m
1c9c0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1c9d0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
1c9e0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
1c9f0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
1ca00 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
1ca10 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
1ca20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a [SQLITE_BUSY]..
1ca30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 **.** ^Calling t
1ca40 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
1ca50 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
1ca60 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
1ca70 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
1ca80 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
1ca90 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ndlers..**.** ^(
1caa0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
1cab0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
1cac0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 handler for a pa
1cad0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
1cae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1caf0 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d ] at any given m
1cb00 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 oment. If anoth
1cb10 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a er busy handler.
1cb20 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 ** was defined
1cb30 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f (using [sqlite3_
1cb40 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 busy_handler()])
1cb50 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
1cb60 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e g.** this routin
1cb70 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 e, that other bu
1cb80 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c sy handler is cl
1cb90 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 eared.)^.**.** S
1cba0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d ee also: [PRAGM
1cbb0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a A busy_timeout].
1cbc0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1cbd0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
1cbe0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 sqlite3_busy_ti
1cbf0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 meout(sqlite3*,
1cc00 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int ms);../*.**
1cc10 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e CAPI3REF: Conven
1cc20 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 ience Routines F
1cc30 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 or Running Queri
1cc40 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
1cc50 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 lite3.**.** This
1cc60 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 is a legacy int
1cc70 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 erface that is p
1cc80 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 reserved for bac
1cc90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1cca0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 lity..** Use of
1ccb0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 this interface i
1ccc0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 s not recommende
1ccd0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 d..**.** Definit
1cce0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 ion: A <b>result
1ccf0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 table</b> is me
1cd00 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 mory data struct
1cd10 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 ure created by t
1cd20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 he.** [sqlite3_g
1cd30 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 et_table()] inte
1cd40 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 rface. A result
1cd50 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 table records t
1cd60 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 he.** complete q
1cd70 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f uery results fro
1cd80 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 m one or more qu
1cd90 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eries..**.** The
1cda0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 table conceptua
1cdb0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 lly has a number
1cdc0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c of rows and col
1cdd0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 umns. But.** th
1cde0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 ese numbers are
1cdf0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 not part of the
1ce00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 result table its
1ce10 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e elf. These.** n
1ce20 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 umbers are obtai
1ce30 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 ned separately.
1ce40 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 Let N be the nu
1ce50 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 mber of rows.**
1ce60 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d and M be the num
1ce70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a ber of columns..
1ce80 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
1ce90 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 able is an array
1cea0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
1ceb0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1cec0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a UTF-8 strings..*
1ced0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 * There are (N+1
1cee0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 )*M elements in
1cef0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 the array. The
1cf00 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 first M pointers
1cf10 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 point.** to zer
1cf20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
1cf30 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 ings that conta
1cf40 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 in the names of
1cf50 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 the columns..**
1cf60 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e The remaining en
1cf70 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 tries all point
1cf80 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 to query results
1cf90 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 . NULL values r
1cfa0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c esult.** in NULL
1cfb0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 pointers. All
1cfc0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 other values are
1cfd0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 in their UTF-8
1cfe0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
1cff0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 ** string repres
1d000 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 entation as retu
1d010 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
1d020 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e _column_text()].
1d030 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
1d040 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 table might cons
1d050 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ist of one or mo
1d060 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 re memory alloca
1d070 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 tions..** It is
1d080 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 not safe to pass
1d090 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
1d0a0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c directly to [sql
1d0b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
1d0c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1d0d0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f should be deallo
1d0e0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cated using [sql
1d0f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1d100 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 )]..**.** ^(As a
1d110 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 n example of the
1d120 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f result table fo
1d130 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 rmat, suppose a
1d140 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 query result.**
1d150 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
1d160 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1d170 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1d180 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 Name | A
1d190 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d ge.** ---
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1d1b0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 ----.** A
1d1c0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a lice | 43.
1d1d0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 ** Bob
1d1e0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 | 28.**
1d1f0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 Cindy
1d200 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c | 21.** </pre><
1d210 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1d220 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f ** There are two
1d230 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 column (M==2) a
1d240 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e nd three rows (N
1d250 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a ==3). Thus the.
1d260 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 ** result table
1d270 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 has 8 entries.
1d280 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 Suppose the resu
1d290 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 lt table is stor
1d2a0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 ed.** in an arra
1d2b0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 y names azResult
1d2c0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 . Then azResult
1d2d0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 holds this cont
1d2e0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ent:.**.** <bloc
1d2f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1d300 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1d310 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b #91;0] = "Name";
1d320 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1d330 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 ult[1] = "Ag
1d340 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1d350 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 Result[2] =
1d360 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 "Alice";.**
1d370 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1d380 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 3] = "43";.**
1d390 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d3a0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 1;4] = "Bob";.**
1d3b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1d3c0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a [5] = "28";.
1d3d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1d3e0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e lt[6] = "Cin
1d3f0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 dy";.** a
1d400 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d zResult[7] =
1d410 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e "21";.** </pre>
1d420 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
1d430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1d440 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 e3_get_table() f
1d450 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 unction evaluate
1d460 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a s one or more.**
1d470 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 semicolon-separ
1d480 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
1d490 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d nts in the zero-
1d4a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
1d4b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 .** string of it
1d4c0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 s 2nd parameter
1d4d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 and returns a re
1d4e0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 sult table to th
1d4f0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 e.** pointer giv
1d500 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 en in its 3rd pa
1d510 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 rameter..**.** A
1d520 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 fter the applica
1d530 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 tion has finishe
1d540 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c d with the resul
1d550 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 t from sqlite3_g
1d560 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 et_table(),.** i
1d570 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 t must pass the
1d580 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 result table poi
1d590 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f nter to sqlite3_
1d5a0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 free_table() in
1d5b0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 order to.** rele
1d5c0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 ase the memory t
1d5d0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 hat was malloced
1d5e0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 . Because of th
1d5f0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 e way the.** [sq
1d600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
1d610 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 happens within s
1d620 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1d630 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a (), the calling.
1d640 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
1d650 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c not try to call
1d660 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1d670 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c ] directly. Onl
1d680 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 y.** [sqlite3_fr
1d690 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 ee_table()] is a
1d6a0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 ble to release t
1d6b0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 he memory proper
1d6c0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a ly and safely..*
1d6d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1d6e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 _get_table() int
1d6f0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
1d700 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 ented as a wrapp
1d710 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
1d720 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 lite3_exec()].
1d730 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
1d740 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 table() routine
1d750 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 does not have ac
1d760 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 cess.** to any i
1d770 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 nternal data str
1d780 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 uctures of SQLit
1d790 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 e. It uses only
1d7a0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 the public.** i
1d7b0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 nterface defined
1d7c0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e here. As a con
1d7d0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 sequence, errors
1d7e0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 that occur in t
1d7f0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 he.** wrapper la
1d800 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 yer outside of t
1d810 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c he internal [sql
1d820 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c ite3_exec()] cal
1d830 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 l are not.** ref
1d840 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 lected in subseq
1d850 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
1d860 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
1d870 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
1d880 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 _errmsg()]..*/.S
1d890 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
1d8a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1d8b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
1d8c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1d8d0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
1d8e0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
1d8f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1d900 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
1d910 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
1d920 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
1d930 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
1d940 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
1d950 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
1d960 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
1d970 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1d980 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
1d990 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
1d9a0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
1d9b0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1d9c0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
1d9d0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
1d9e0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
1d9f0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
1da00 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
1da10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1da20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1da30 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1da40 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
1da50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1da60 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
1da70 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
1da80 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
1da90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1daa0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 work-alikes of
1dab0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
1dac0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
1dad0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
1dae0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1daf0 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 y..** These rout
1db00 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 ines understand
1db10 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d most of the comm
1db20 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e on K&R formattin
1db30 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c g options,.** pl
1db40 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e us some addition
1db50 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 al non-standard
1db60 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 formats, detaile
1db70 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 d below..** Note
1db80 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 that some of th
1db90 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 e more obscure f
1dba0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1dbb0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a s from recent.**
1dbc0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 C-library stand
1dbd0 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 ards are omitted
1dbe0 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 from this imple
1dbf0 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a mentation..**.**
1dc00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 ^The sqlite3_mp
1dc10 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 rintf() and sqli
1dc20 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 te3_vmprintf() r
1dc30 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 outines write th
1dc40 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 eir.** results i
1dc50 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
1dc60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
1dc70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 3_malloc()]..**
1dc80 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 The strings retu
1dc90 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 rned by these tw
1dca0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c o routines shoul
1dcb0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 d be.** released
1dcc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 by [sqlite3_fre
1dcd0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 e()]. ^Both rou
1dce0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a tines return a.*
1dcf0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
1dd00 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1dd10 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 c()] is unable t
1dd20 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 o allocate enoug
1dd30 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 h.** memory to h
1dd40 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e old the resultin
1dd50 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 g string..**.**
1dd60 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e ^(The sqlite3_sn
1dd70 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1dd80 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
1dd90 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
1dda0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
1ddb0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
1ddc0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
1ddd0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
1dde0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
1ddf0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
1de00 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
1de10 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
1de20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1de30 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
1de40 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
1de50 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
1de60 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
1de70 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
1de80 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 tf().)^ This is
1de90 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 an.** historica
1dea0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 l accident that
1deb0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 cannot be fixed
1dec0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
1ded0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
1dee0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 mpatibility. ^(
1def0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 Note also that s
1df00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1df10 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 ).** returns a p
1df20 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 ointer to its bu
1df30 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 ffer instead of
1df40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
1df50 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 characters actu
1df60 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 ally written int
1df70 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 o the buffer.)^
1df80 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a We admit that.*
1df90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
1dfa0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 characters writt
1dfb0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f en would be a mo
1dfc0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e re useful return
1dfd0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 .** value but we
1dfe0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 cannot change t
1dff0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
1e000 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
1e010 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 rintf().** now w
1e020 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
1e030 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
1e040 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 *.** ^As long as
1e050 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 the buffer size
1e060 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e is greater than
1e070 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 zero, sqlite3_s
1e080 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 nprintf().** gua
1e090 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
1e0a0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 buffer is alway
1e0b0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
1e0c0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a d. ^The first.*
1e0d0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 * parameter "n"
1e0e0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a is the total siz
1e0f0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c e of the buffer,
1e100 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 including space
1e110 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f for.** the zero
1e120 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f terminator. So
1e130 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 the longest str
1e140 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 ing that can be
1e150 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 completely.** wr
1e160 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d itten will be n-
1e170 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 1 characters..**
1e180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e190 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 _vsnprintf() rou
1e1a0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 tine is a vararg
1e1b0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c s version of sql
1e1c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e ite3_snprintf().
1e1d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1e1e0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d tines all implem
1e1f0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f ent some additio
1e200 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a nal formatting.*
1e210 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 * options that a
1e220 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
1e230 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 nstructing SQL s
1e240 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c tatements..** Al
1e250 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 l of the usual p
1e260 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 rintf() formatti
1e270 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 ng options apply
1e280 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 . In addition,
1e290 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 there.** is are
1e2a0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 "%q", "%Q", "%w"
1e2b0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
1e2c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 s..**.** ^(The %
1e2d0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
1e2e0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
1e2f0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
1e300 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
1e310 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 * string from th
1e320 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e e argument list.
1e330 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f But %q also do
1e340 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 ubles every '\''
1e350 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 character..** %
1e360 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f q is designed fo
1e370 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 r use inside a s
1e380 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e tring literal.)^
1e390 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 By doubling ea
1e3a0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 ch '\''.** chara
1e3b0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 cter it escapes
1e3c0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 that character a
1e3d0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 nd allows it to
1e3e0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f be inserted into
1e3f0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a .** the string..
1e400 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c **.** For exampl
1e410 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 e, assume the st
1e420 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 ring variable zT
1e430 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 ext contains tex
1e440 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
1e450 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1e460 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1e470 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 zText = "It's a
1e480 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 happy day!";.**
1e490 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1e4a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 te>.**.** One ca
1e4b0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 n use this text
1e4c0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
1e4d0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ent as follows:.
1e4e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1e4f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1e500 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
1e510 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
1e520 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
1e530 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 ES('%q')", zText
1e540 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
1e550 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
1e560 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
1e570 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
1e580 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1e590 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 quote>.**.** Bec
1e5a0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d ause the %q form
1e5b0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 at string is use
1e5c0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 d, the '\'' char
1e5d0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a acter in zText.*
1e5e0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 * is escaped and
1e5f0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 the SQL generat
1e600 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ed is as follows
1e610 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1e620 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e ote><pre>.** IN
1e630 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 SERT INTO table1
1e640 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 VALUES('It''s a
1e650 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a happy day!').**
1e660 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1e670 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ote>.**.** This
1e680 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 is correct. Had
1e690 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 we used %s inst
1e6a0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 ead of %q, the g
1e6b0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 enerated SQL.**
1e6c0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 would have looke
1e6d0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a d like this:.**.
1e6e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1e6f0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
1e700 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
1e710 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 ES('It's a happy
1e720 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 day!');.** </pr
1e730 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1e740 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e **.** This secon
1e750 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 d example is an
1e760 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 SQL syntax error
1e770 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 . As a general
1e780 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a rule you should.
1e790 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 ** always use %q
1e7a0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 instead of %s w
1e7b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 hen inserting te
1e7c0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 xt into a string
1e7d0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 literal..**.**
1e7e0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 ^(The %Q option
1e7f0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 works like %q ex
1e800 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 cept it also add
1e810 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 s single quotes
1e820 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 around.** the ou
1e830 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 tside of the tot
1e840 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 al string. Addi
1e850 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 tionally, if the
1e860 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
1e870 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 e.** argument li
1e880 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 st is a NULL poi
1e890 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 nter, %Q substit
1e8a0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e utes the text "N
1e8b0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a ULL" (without.**
1e8c0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e single quotes).
1e8d0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d )^ So, for exam
1e8e0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 ple, one could s
1e8f0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ay:.**.** <block
1e900 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e910 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
1e920 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
1e930 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
1e940 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 VALUES(%Q)", zTe
1e950 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1e960 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1e970 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1e980 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1e990 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1e9a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1e9b0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 he code above wi
1e9c0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 ll render a corr
1e9d0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ect SQL statemen
1e9e0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a t in the zSQL.**
1e9f0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 variable even i
1ea00 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 f the zText vari
1ea10 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 able is a NULL p
1ea20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ointer..**.** ^(
1ea30 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 The "%w" formatt
1ea40 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 ing option is li
1ea50 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 ke "%q" except t
1ea60 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 hat it expects t
1ea70 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 o.** be containe
1ea80 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d d within double-
1ea90 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f quotes instead o
1eaa0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c f single quotes,
1eab0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 and it.** escap
1eac0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 es the double-qu
1ead0 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e ote character in
1eae0 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e stead of the sin
1eaf0 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 gle-quote.** cha
1eb00 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 racter.)^ The "
1eb10 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %w" formatting o
1eb20 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 ption is intende
1eb30 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 d for safely ins
1eb40 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 erting.** table
1eb50 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 and column names
1eb60 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 into a construc
1eb70 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
1eb80 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 t..**.** ^(The "
1eb90 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
1eba0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1ebb0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
1ebc0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
1ebd0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
1ebe0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
1ebf0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
1ec00 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
1ec10 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
1ec20 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
1ec30 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1ec40 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
1ec50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 I char *SQLITE_C
1ec60 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70 72 DECL sqlite3_mpr
1ec70 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
1ec80 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,...);.SQLITE_AP
1ec90 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 I char *SQLITE_S
1eca0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
1ecb0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1ecc0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 ar*, va_list);.S
1ecd0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
1ece0 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c SQLITE_CDECL sql
1ecf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e ite3_snprintf(in
1ed00 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t,char*,const ch
1ed10 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 ar*, ...);.SQLIT
1ed20 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 E_API char *SQLI
1ed30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1ed40 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 e3_vsnprintf(int
1ed50 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
1ed60 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f r*, va_list);../
1ed70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1ed80 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
1ed90 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a Subsystem.**.**
1eda0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
1edb0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 uses these thre
1edc0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 e routines for a
1edd0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a ll of its own.**
1ede0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
1edf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
1ee00 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 s. "Core" in the
1ee10 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
1ee20 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 ce.** does not i
1ee30 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 nclude operating
1ee40 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
1ee50 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
1ee60 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e ion. The.** Win
1ee70 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 dows VFS uses na
1ee80 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e tive malloc() an
1ee90 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d d free() for som
1eea0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
1eeb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1eec0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
1eed0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
1eee0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
1eef0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
1ef00 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1ef10 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
1ef20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
1ef30 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
1ef40 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
1ef50 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
1ef60 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
1ef70 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
1ef80 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
1ef90 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 er. ^If the par
1efa0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
1efb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1efc0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
1efd0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
1efe0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
1eff0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
1f000 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
1f010 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
1f020 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b (N) routine work
1f030 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 s just like.** s
1f040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1f050 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 except that N i
1f060 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 s an unsigned 64
1f070 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 -bit integer ins
1f080 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 tead.** of a sig
1f090 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 ned 32-bit integ
1f0a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 er..**.** ^Calli
1f0b0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
1f0c0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
1f0d0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
1f0e0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
1f0f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
1f100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1f110 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
1f120 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
1f130 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
1f140 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 sed. ^The sqlit
1f150 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
1f160 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
1f170 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
1f180 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1f190 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
1f1a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
1f1b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1f1c0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
1f1d0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
1f1e0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
1f1f0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
1f200 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
1f210 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
1f220 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
1f230 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
1f240 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
1f250 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
1f260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1f270 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
1f280 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
1f290 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
1f2a0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1f2b0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
1f2c0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
1f2d0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
1f2e0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
1f2f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
1f300 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
1f310 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1f320 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1f330 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
1f340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f350 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e _realloc(X,N) in
1f360 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
1f370 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 to resize a.**
1f380 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c prior memory all
1f390 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 ocation X to be
1f3a0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
1f3b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 ..** ^If the X p
1f3c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1f3d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1f3e0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
1f3f0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
1f400 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
1f410 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
1f420 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1f430 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 c(N)..** ^If the
1f440 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 N parameter to
1f450 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f460 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a X,N) is zero or.
1f470 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
1f480 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1f490 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
1f4a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
1f4b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e sqlite3_free(X).
1f4c0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
1f4d0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1f4e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1f4f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1f500 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 on.** of at leas
1f510 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a t N bytes in siz
1f520 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 e or NULL if ins
1f530 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
1f540 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a is available..*
1f550 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 * ^If M is the s
1f560 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
1f570 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
1f580 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
1f590 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
1f5a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
1f5b0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
1f5c0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
1f5d0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
1f5e0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
1f5f0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 oc(X,N) and the
1f600 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1f610 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 is freed..** ^I
1f620 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f f sqlite3_reallo
1f630 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e c(X,N) returns N
1f640 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 ULL and N is pos
1f650 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a itive, then the.
1f660 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 ** prior allocat
1f670 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 ion is not freed
1f680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1f690 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 ite3_realloc64(X
1f6a0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 ,N) interfaces w
1f6b0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 orks the same as
1f6c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c .** sqlite3_real
1f6d0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 loc(X,N) except
1f6e0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 that N is a 64-b
1f6f0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
1f700 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ger instead.** o
1f710 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 f a 32-bit signe
1f720 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a d integer..**.**
1f730 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f ^If X is a memo
1f740 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 ry allocation pr
1f750 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
1f760 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1f770 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 alloc(),.** sqli
1f780 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 te3_malloc64(),
1f790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f7a0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ), or sqlite3_re
1f7b0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a alloc64(), then.
1f7c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
1f7d0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 (X) returns the
1f7e0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d size of that mem
1f7f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ory allocation i
1f800 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 n bytes..** ^The
1f810 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1f820 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 by sqlite3_msize
1f830 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 (X) might be lar
1f840 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d ger than the num
1f850 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 ber.** of bytes
1f860 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 requested when X
1f870 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 was allocated.
1f880 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c ^If X is a NULL
1f890 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a pointer then.**
1f8a0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1f8b0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 ) returns zero.
1f8c0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 If X points to
1f8d0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 something that i
1f8e0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 s not.** the beg
1f8f0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 inning of memory
1f900 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 allocation, or
1f910 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 if it points to
1f920 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 a formerly.** va
1f930 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 lid memory alloc
1f940 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e ation that has n
1f950 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 ow been freed, t
1f960 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1f970 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d .** of sqlite3_m
1f980 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 size(X) is undef
1f990 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c ined and possibl
1f9a0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a y harmful..**.**
1f9b0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
1f9c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1f9d0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 _malloc(), sqlit
1f9e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a e3_realloc(),.**
1f9f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 sqlite3_malloc6
1fa00 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 4(), and sqlite3
1fa10 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 _realloc64().**
1fa20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 is always aligne
1fa30 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e d to at least an
1fa40 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8 byte boundary
1fa50 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 , or to a.** 4 b
1fa60 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 yte boundary if
1fa70 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 the [SQLITE_4_BY
1fa80 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f TE_ALIGNED_MALLO
1fa90 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a C] compile-time.
1faa0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 ** option is use
1fab0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 d..**.** In SQLi
1fac0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
1fad0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 and 3.5.1, it w
1fae0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 as possible to d
1faf0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c efine.** the SQL
1fb00 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f ITE_OMIT_MEMORY_
1fb10 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 ALLOCATION which
1fb20 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 would cause the
1fb30 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 built-in.** imp
1fb40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
1fb50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f hese routines to
1fb60 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 be omitted. Th
1fb70 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a at capability.**
1fb80 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 is no longer pr
1fb90 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 ovided. Only bu
1fba0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
1fbb0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 locators can be
1fbc0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f used..**.** Prio
1fbd0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 r to SQLite vers
1fbe0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 ion 3.7.10, the
1fbf0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 Windows OS inter
1fc00 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 face layer calle
1fc10 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 d.** the system
1fc20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
1fc30 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
1fc40 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
1fc50 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
1fc60 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
1fc70 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
1fc80 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
1fc90 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
1fca0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
1fcb0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
1fcc0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 Windows.** insta
1fcd0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
1fce0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
1fcf0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 rs were detected
1fd00 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 , but.** they we
1fd10 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b re reported back
1fd20 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 as [SQLITE_CANT
1fd30 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c OPEN] or.** [SQL
1fd40 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 ITE_IOERR] rathe
1fd50 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e r than [SQLITE_N
1fd60 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 OMEM]..**.** The
1fd70 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
1fd80 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ts to [sqlite3_f
1fd90 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ree()] and [sqli
1fda0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
1fdb0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 * must be either
1fdc0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f NULL or else po
1fdd0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 inters obtained
1fde0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 from a prior.**
1fdf0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
1fe00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1fe10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
1fe20 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 lloc()] that hav
1fe30 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 e.** not yet bee
1fe40 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a n released..**.*
1fe50 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
1fe60 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 n must not read
1fe70 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 or write any par
1fe80 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 t of.** a block
1fe90 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 of memory after
1fea0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 it has been rele
1feb0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ased using.** [s
1fec0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f qlite3_free()] o
1fed0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
1fee0 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 oc()]..*/.SQLITE
1fef0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
1ff00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1ff10 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 3_malloc(int);.S
1ff20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
1ff30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1ff40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1ff50 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b sqlite3_uint64);
1ff60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1ff70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1ff80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1ff90 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 (void*, int);.SQ
1ffa0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 LITE_API void *S
1ffb0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1ffc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
1ffd0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
1ffe0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
1fff0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 PI void SQLITE_S
20000 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 TDCALL sqlite3_f
20010 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 ree(void*);.SQLI
20020 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 TE_API sqlite3_u
20030 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
20040 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73 69 CALL sqlite3_msi
20050 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ze(void*);../*.*
20060 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
20070 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 ry Allocator Sta
20080 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 tistics.**.** SQ
20090 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
200a0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
200b0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
200c0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
200d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
200e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
200f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
20100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
20110 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
20120 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
20130 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
20140 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
20150 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e bsystem..**.** ^
20160 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
20170 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 ory_used()] rout
20180 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
20190 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a number of bytes.
201a0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 ** of memory cur
201b0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 rently outstandi
201c0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 ng (malloced but
201d0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 not freed)..**
201e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
201f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
20200 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
20210 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
20220 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
20230 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
20240 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 ] since the high
20250 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 -water mark.** w
20260 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 as last reset.
20270 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
20280 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
20290 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
202a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
202b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
202c0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 ()] include any
202d0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 overhead.** adde
202e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
202f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
20300 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
20310 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 lloc()],.** but
20320 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 not overhead add
20330 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e ed by the any un
20340 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 derlying system
20350 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 library.** routi
20360 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 nes that [sqlite
20370 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 3_malloc()] may
20380 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 call..**.** ^The
20390 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 memory high-wat
203a0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 er mark is reset
203b0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
203c0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c value of.** [sql
203d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
203e0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ()] if and only
203f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
20400 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
20410 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20420 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 ()] is true. ^T
20430 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
20440 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
20450 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20460 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 r(1)] is the hig
20470 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
20480 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
20490 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
204a0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
204b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
204c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
204d0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 ed(void);.SQLITE
204e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
204f0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
20500 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
20510 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 _highwater(int r
20520 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a esetFlag);../*.*
20530 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 * CAPI3REF: Pseu
20540 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 do-Random Number
20550 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a Generator.**.**
20560 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 SQLite contains
20570 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 a high-quality
20580 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 pseudo-random nu
20590 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 mber generator (
205a0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a PRNG) used to.**
205b0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b select random [
205c0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 ROWID | ROWIDs]
205d0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e when inserting n
205e0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 ew records into
205f0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 a table that.**
20600 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 already uses the
20610 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c largest possibl
20620 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 e [ROWID]. The
20630 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 PRNG is also use
20640 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 d for.** the bui
20650 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 ld-in random() a
20660 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 nd randomblob()
20670 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 SQL functions.
20680 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
20690 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 llows.** applica
206a0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 tions to access
206b0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f the same PRNG fo
206c0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 r other purposes
206d0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 ..**.** ^A call
206e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
206f0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f stores N bytes o
20700 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 f randomness int
20710 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e o buffer P..** ^
20720 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 The P parameter
20730 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f can be a NULL po
20740 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 inter..**.** ^If
20750 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
20760 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 s not been previ
20770 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 ously called or
20780 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a if the previous.
20790 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 ** call had N le
207a0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 ss than one or a
207b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
207c0 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 r P, then the PR
207d0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 NG is.** seeded
207e0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
207f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 obtained from t
20800 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d he xRandomness m
20810 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 ethod of.** the
20820 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
20830 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
20840 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 ^If the previou
20850 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 s call to this r
20860 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 outine had an N
20870 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 of 1 or more and
20880 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 a.** non-NULL P
20890 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f then the pseudo
208a0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
208b0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
208c0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
208d0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
208e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
208f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
20900 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 method..*/.SQLIT
20910 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
20920 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
20930 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 3_randomness(int
20940 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f N, void *P);../
20950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
20960 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 ompile-Time Auth
20970 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 orization Callba
20980 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 cks.** METHOD: s
20990 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
209a0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
209b0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a ters an authoriz
209c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
209d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
209e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
209f0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
20a00 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
20a10 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
20a20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20a30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ack is invoked a
20a40 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 s SQL statements
20a50 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 are being compi
20a60 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 led.** by [sqlit
20a70 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
20a80 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 its variants [s
20a90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20aa0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
20ab0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 3_prepare16()] a
20ac0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
20ad0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 are16_v2()]. ^A
20ae0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 t various.** poi
20af0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 nts during the c
20b00 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 ompilation proce
20b10 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 ss, as logic is
20b20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a being created.**
20b30 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
20b40 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 ous actions, the
20b50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20b60 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
20b70 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f to.** see if tho
20b80 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 se actions are a
20b90 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 llowed. ^The au
20ba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20bb0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 k should.** retu
20bc0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 rn [SQLITE_OK] t
20bd0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 o allow the acti
20be0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f on, [SQLITE_IGNO
20bf0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 RE] to disallow
20c00 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
20c10 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 action but allow
20c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
20c30 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 nt to continue t
20c40 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 o be.** compiled
20c50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
20c60 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 Y] to cause the
20c70 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 entire SQL state
20c80 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 ment to be.** re
20c90 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 jected with an e
20ca0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 rror. ^If the a
20cb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20cc0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ck returns.** an
20cd0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
20ce0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 an [SQLITE_IGNOR
20cf0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c E], [SQLITE_OK],
20d00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
20d10 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 ].** then the [s
20d20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20d30 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
20d40 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
20d50 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 ggered.** the au
20d60 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
20d70 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
20d80 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
20d90 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
20da0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
20db0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e E_OK], that mean
20dc0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a s the operation.
20dd0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 ** requested is
20de0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 ok. ^When the c
20df0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
20e00 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 [SQLITE_DENY], t
20e10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 he.** [sqlite3_p
20e20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
20e30 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
20e40 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
20e50 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
20e60 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
20e70 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
20e80 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 explaining that
20e90 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 .** access is de
20ea0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 nied. .**.** ^Th
20eb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
20ec0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
20ed0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
20ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
20ef0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
20f00 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
20f10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
20f20 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 interface. ^The
20f30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
20f40 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c r.** to the call
20f50 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
20f60 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 er [SQLITE_COPY
20f70 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 | action code] t
20f80 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
20f90 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
20fa0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
20fb0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 horized. ^The th
20fc0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
20fd0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 h parameters.**
20fe0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
20ff0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 are zero-termina
21000 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
21010 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f contain additio
21020 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 nal.** details a
21030 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 bout the action
21040 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
21050 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
21060 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
21070 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
21080 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
21090 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
210a0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
210b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
210c0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
210d0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
210e0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
210f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
21100 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
21110 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
21120 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
21130 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
21140 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
21150 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
21160 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
21170 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
21180 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
21190 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
211a0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
211b0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
211c0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
211d0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
211e0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
211f0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 DELETE] and the
21200 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
21210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f .** [SQLITE_IGNO
21220 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 RE] then the [DE
21230 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 LETE] operation
21240 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 proceeds but the
21250 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 .** [truncate op
21260 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 timization] is d
21270 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 isabled and all
21280 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 rows are deleted
21290 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a individually..*
212a0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a *.** An authoriz
212b0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 er is used when
212c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
212d0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a | preparing].**
212e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
212f0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 from an untruste
21300 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 d source, to ens
21310 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ure that the SQL
21320 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 statements.** d
21330 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 o not try to acc
21340 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 ess data they ar
21350 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f e not allowed to
21360 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 see, or that th
21370 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 ey do not.** try
21380 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 to execute mali
21390 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 cious statements
213a0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 that damage the
213b0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a database. For.
213c0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 ** example, an a
213d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 pplication may a
213e0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 llow a user to e
213f0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a nter arbitrary.*
21400 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f * SQL queries fo
21410 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 r evaluation by
21420 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 a database. But
21430 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
21440 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
21450 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 t the user to be
21460 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 able to make ar
21470 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 bitrary changes
21480 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 to the.** databa
21490 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a se. An authoriz
214a0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 er could then be
214b0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 put in place wh
214c0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d ile the.** user-
214d0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 entered SQL is b
214e0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 eing [sqlite3_pr
214f0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 epare | prepared
21500 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c ] that.** disall
21510 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 ows everything e
21520 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 xcept [SELECT] s
21530 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
21540 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
21550 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 at need to proce
21560 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 ss SQL from untr
21570 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a usted sources.**
21580 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 might also cons
21590 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 ider lowering re
215a0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 source limits us
215b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
215c0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d it()].** and lim
215d0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 iting database s
215e0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d ize using the [m
215f0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b ax_page_count] [
21600 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 PRAGMA].** in ad
21610 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 dition to using
21620 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a an authorizer..*
21630 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 *.** ^(Only a si
21640 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ngle authorizer
21650 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 can be in place
21660 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f on a database co
21670 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 nnection.** at a
21680 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c time. Each cal
21690 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 l to sqlite3_set
216a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 _authorizer over
216b0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 rides the.** pre
216c0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e vious call.)^ ^
216d0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 Disable the auth
216e0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c orizer by instal
216f0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c ling a NULL call
21700 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 back..** The aut
21710 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 horizer is disab
21720 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
21730 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
21740 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 izer callback mu
21750 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
21760 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
21770 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
21780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
21790 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
217a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
217b0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ack..** Note tha
217c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
217d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
217e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
217f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
21800 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
21810 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
21820 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
21830 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
21840 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 graph..**.** ^Wh
21850 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
21860 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
21870 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
21880 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
21890 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
218a0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 be re-prepared
218b0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f during [sqlite3_
218c0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 step()] due to a
218d0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e .** schema chan
218e0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 ge. Hence, the
218f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
21900 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 ld ensure that t
21910 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 he.** correct au
21920 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21930 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 k remains in pla
21940 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 ce during the [s
21950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
21960 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
21970 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21980 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
21990 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
219a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
219b0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
219c0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
219d0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
219e0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
219f0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
21a00 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
21a10 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 e3_step()], unle
21a20 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 ss.** as stated
21a30 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
21a40 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 paragraph, sqlit
21a50 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 e3_step() invoke
21a60 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 s.** sqlite3_pre
21a70 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 pare_v2() to rep
21a80 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 repare a stateme
21a90 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d nt after a schem
21aa0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c a change..*/.SQL
21ab0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
21ac0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
21ad0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21ae0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 r(. sqlite3*,.
21af0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f int (*xAuth)(vo
21b00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
21b10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
21b20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
21b30 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 t char*),. void
21b40 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a *pUserData.);..
21b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21b60 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 Authorizer Retur
21b70 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 n Codes.**.** Th
21b80 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
21b90 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
21ba0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21bb0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a function] must.*
21bc0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 * return either
21bd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f [SQLITE_OK] or o
21be0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 ne of these two
21bf0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 constants in ord
21c00 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 er.** to signal
21c10 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f SQLite whether o
21c20 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e r not the action
21c30 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 is permitted.
21c40 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 See the.** [sqli
21c50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
21c60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
21c70 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
21c80 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
21c90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
21ca0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
21cb0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 LITE_IGNORE is a
21cc0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 lso used as a [c
21cd0 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 onflict resoluti
21ce0 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 on mode].** retu
21cf0 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 rned from the [s
21d00 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 qlite3_vtab_on_c
21d10 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 onflict()] inter
21d20 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 face..*/.#define
21d30 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 SQLITE_DENY 1
21d40 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 /* Abort the
21d50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 SQL statement wi
21d60 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 th an error */.#
21d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 define SQLITE_IG
21d80 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 NORE 2 /* Don'
21d90 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 t allow access,
21da0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 but don't genera
21db0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a te an error */..
21dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21dd0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f Authorizer Actio
21de0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 n Codes.**.** Th
21df0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
21e00 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 uthorizer()] int
21e10 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
21e20 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
21e30 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 tion.** that is
21e40 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f invoked to autho
21e50 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c rize certain SQL
21e60 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f statement actio
21e70 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ns. The.** seco
21e80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
21e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
21ea0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
21eb0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
21ec0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 * what action is
21ed0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
21ee0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 d. These are th
21ef0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e e integer action
21f00 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 codes that.** t
21f10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
21f20 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 llback may be pa
21f30 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ssed..**.** Thes
21f40 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 e action code va
21f50 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 lues signify wha
21f60 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 t kind of operat
21f70 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 ion is to be.**
21f80 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
21f90 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 3rd and 4th par
21fa0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 ameters to the a
21fb0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 uthorization.**
21fc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
21fd0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 n will be parame
21fe0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 ters or NULL dep
21ff0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 ending on which
22000 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 of these.** code
22010 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 s is used as the
22020 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
22030 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 r. ^(The 5th pa
22040 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a rameter to the.*
22050 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c * authorizer cal
22060 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d lback is the nam
22070 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
22080 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e ("main", "temp
22090 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 ",.** etc.) if a
220a0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 pplicable.)^ ^T
220b0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 he 6th parameter
220c0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
220d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 er callback.** i
220e0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
220f0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
22100 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
22110 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
22120 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 for.** the acce
22130 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
22140 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
22150 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
22160 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f ectly from.** to
22170 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 p-level SQL code
22180 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
22190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
221a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
221b0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
221c0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
221d0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
221e0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
221f0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
22200 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
22210 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22230 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
22240 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
22250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
22260 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22280 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
22290 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
222a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
222b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
222c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
222d0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
222e0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
222f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
22300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22320 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
22330 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
22340 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
22350 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
22360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22370 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
22380 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
22390 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
223a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
223b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
223c0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
223d0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
223e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
223f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
22410 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
22420 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
22430 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
22440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22450 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
22460 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
22470 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
22480 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
224a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
224b0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
224c0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
224d0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
224e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
224f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
22500 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
22510 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22540 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
22550 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
22560 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
22570 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
22580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22590 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
225a0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
225b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
225c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
225d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
225e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
225f0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
22600 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
22610 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22630 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
22640 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
22650 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
22660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22680 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
22690 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
226a0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
226b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
226c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
226d0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
226e0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
226f0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
22700 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22720 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
22730 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
22740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
22750 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22770 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
22780 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
22790 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
227a0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
227b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
227c0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
227d0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
227e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
227f0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
22800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
22810 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
22820 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
22830 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
22840 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
22860 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
22870 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 22 /* Opera
22880 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 tion NULL
22890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
228a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
228b0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
228c0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
228d0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
228e0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
228f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
22900 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
22910 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
22920 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
22930 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22940 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
22950 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
22960 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
22970 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
22980 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22990 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
229a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
229b0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
229c0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
229d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
229e0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
229f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
22a00 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
22a10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22a20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22a30 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
22a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
22a50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22a60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22a80 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
22a90 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
22aa0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22ab0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
22ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22ad0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
22ae0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
22af0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
22b00 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
22b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22b20 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
22b30 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
22b40 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
22b50 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 Function Name
22b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22b70 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 ITE_SAVEPOINT
22b80 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 32 /*
22b90 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
22ba0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 Savepoint Name
22bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22bc0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 TE_COPY
22bd0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
22be0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a No longer used *
22bf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22c00 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 _RECURSIVE
22c10 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 33 /* NU
22c20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
22c30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22c40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22c50 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 : Tracing And Pr
22c60 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e ofiling Function
22c70 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
22c80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ite3.**.** These
22c90 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
22ca0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
22cb0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
22cc0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
22cd0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
22ce0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
22cf0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
22d00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
22d10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
22d20 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
22d30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22d40 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
22d50 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
22d60 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
22d70 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
22d80 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
22d90 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
22da0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
22db0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
22dc0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
22dd0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
22de0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
22df0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
22e00 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
22e10 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
22e20 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
22e30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22e40 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
22e50 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
22e60 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
22e70 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
22e80 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
22e90 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
22ea0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
22eb0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
22ec0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
22ed0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
22ee0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
22ef0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
22f00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
22f10 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
22f20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
22f30 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
22f40 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
22f50 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
22f60 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
22f70 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
22f80 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
22f90 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
22fa0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
22fb0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
22fc0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
22fd0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
22fe0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
22ff0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
23000 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
23010 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
23020 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
23030 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
23040 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
23050 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
23060 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
23070 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
23080 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
23090 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
230a0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
230b0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
230c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
230d0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
230e0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
230f0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
23100 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
23110 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
23120 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
23130 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
23140 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
23150 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
23160 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
23170 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
23180 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
23190 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
231a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
231b0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
231c0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
231d0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
231e0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
231f0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
23200 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
23210 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
23220 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
23230 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 LL sqlite3_trace
23240 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
23250 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
23260 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
23270 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 d*);.SQLITE_API
23280 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
23290 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 TAL void *SQLITE
232a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
232b0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 _profile(sqlite3
232c0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f *,. void(*xPro
232d0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 file)(void*,cons
232e0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f t char*,sqlite3_
232f0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
23300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23310 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 : Query Progress
23320 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 Callbacks.** ME
23330 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
23340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
23350 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
23360 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 r(D,N,X,P) inter
23370 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 face causes the
23380 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
23390 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 tion X to be inv
233a0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c oked periodicall
233b0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 y during long ru
233c0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a nning calls to.*
233d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * [sqlite3_exec(
233e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
233f0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 p()] and [sqlite
23400 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 3_get_table()] f
23410 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 or.** database c
23420 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e onnection D. An
23430 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 example use for
23440 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 this.** interfa
23450 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 ce is to keep a
23460 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 GUI updated duri
23470 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 ng a large query
23480 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 ..**.** ^The par
23490 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 ameter P is pass
234a0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
234b0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
234c0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c to the .** call
234d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e back function X.
234e0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 ^The parameter
234f0 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 N is the approx
23500 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 imate number of
23510 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 .** [virtual mac
23520 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e hine instruction
23530 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c s] that are eval
23540 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 uated between su
23550 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f ccessive.** invo
23560 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 cations of the c
23570 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 allback X. ^If
23580 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
23590 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 ne then the prog
235a0 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 ress.** handler
235b0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a is disabled..**.
235c0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c ** ^Only a singl
235d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
235e0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 er may be define
235f0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 d at one time pe
23600 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
23610 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 onnection]; sett
23620 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 ing a new progre
23630 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 ss handler cance
23640 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e ls the.** old on
23650 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 e. ^Setting par
23660 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c ameter X to NULL
23670 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 disables the pr
23680 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
23690 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 ** ^The progress
236a0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f handler is also
236b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 disabled by set
236c0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 ting N to a valu
236d0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 e less.** than 1
236e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
236f0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
23700 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
23710 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f ro, the operatio
23720 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 n is.** interrup
23730 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 ted. This featu
23740 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 re can be used t
23750 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a o implement a.**
23760 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e "Cancel" button
23770 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 on a GUI progre
23780 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a ss dialog box..*
23790 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 *.** The progres
237a0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 s handler callba
237b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
237c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
237d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
237e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
237f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
23800 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
23810 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 ndler..** Note t
23820 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
23830 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
23840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
23850 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
23860 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
23870 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
23880 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
23890 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
238a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 ragraph..**.*/.S
238b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
238c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
238d0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
238e0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
238f0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
23900 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
23910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
23920 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
23930 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
23940 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
23950 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
23960 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
23970 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
23980 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 abase file as sp
23990 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ecified by the .
239a0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
239b0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e ment. ^The filen
239c0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
239d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
239e0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
239f0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
23a00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
23a10 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
23a20 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
23a30 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
23a40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
23a50 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 ^(A [database c
23a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
23a70 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
23a80 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
23a90 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
23aa0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
23ab0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
23ac0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
23ad0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
23ae0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
23af0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
23b00 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
23b10 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
23b20 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
23b30 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
23b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
23b50 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
23b60 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 ject.)^ ^(If the
23b70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
23b80 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
23b90 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
23ba0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
23bb0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
23bc0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
23bd0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
23be0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 s returned.)^ ^T
23bf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
23c00 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
23c10 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
23c20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
23c30 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
23c40 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
23c50 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
23c60 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 on of the error
23c70 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
23c80 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ure of any.** of
23c90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 the sqlite3_ope
23ca0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a n() routines..**
23cb0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
23cc0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 encoding will b
23cd0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 e UTF-8 for data
23ce0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 bases created us
23cf0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f ing.** sqlite3_o
23d00 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
23d10 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 _open_v2(). ^Th
23d20 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
23d30 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 ng for databases
23d40 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e .** created usin
23d50 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 g sqlite3_open16
23d60 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 () will be UTF-1
23d70 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
23d80 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
23d90 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
23da0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
23db0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
23dc0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
23dd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
23de0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
23df0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
23e00 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
23e10 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
23e20 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
23e30 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
23e40 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
23e50 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
23e60 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
23e70 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
23e80 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
23e90 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
23ea0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
23eb0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
23ec0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
23ed0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
23ee0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
23ef0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
23f00 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
23f10 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
23f20 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
23f30 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
23f40 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
23f50 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
23f60 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
23f70 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
23f80 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
23f90 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
23fa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
23fb0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
23fc0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
23fd0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
23fe0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
23ff0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
24000 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
24010 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
24020 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
24030 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
24040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
24050 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
24060 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
24070 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
24080 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
24090 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
240a0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
240b0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
240c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
240d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
240e0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
240f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
24100 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
24110 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
24120 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
24130 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
24140 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
24150 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
24160 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
24170 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
24180 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
24190 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
241a0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
241b0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
241c0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
241d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
241e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
241f0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
24200 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
24210 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
24220 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
24230 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
24240 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
24250 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
24260 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
24270 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
24280 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
24290 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
242a0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
242b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
242c0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
242d0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
242e0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
242f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
24300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
24310 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
24320 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
24330 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
24340 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
24350 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
24360 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
24370 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
24380 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
24390 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
243a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
243b0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
243c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
243d0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
243e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
243f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
24400 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
24410 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
24420 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
24430 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
24440 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
24450 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
24460 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
24470 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
24480 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
24490 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
244a0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
244b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
244c0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
244d0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
244e0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
244f0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
24500 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
24510 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
24520 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
24530 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
24540 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
24550 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
24560 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
24570 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
24580 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
24590 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
245a0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
245b0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
245c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
245d0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
245e0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
245f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
24600 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
24610 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
24620 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
24630 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
24640 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
24650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
24660 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
24670 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
24680 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
24690 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
246a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
246b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
246c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
246d0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
246e0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
246f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
24700 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
24710 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
24720 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
24730 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
24740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
24750 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
24760 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
24770 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
24780 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
24790 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
247a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
247b0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
247c0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
247d0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
247e0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
247f0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
24800 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
24810 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
24820 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
24830 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
24840 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
24850 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
24860 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24870 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
24880 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
24890 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
248a0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
248b0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
248c0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
248d0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
248e0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
248f0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
24900 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
24910 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
24920 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
24930 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
24940 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
24950 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
24960 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
24970 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
24980 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
24990 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
249a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
249b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
249c0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
249d0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
249e0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
249f0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
24a00 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
24a10 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
24a20 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
24a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
24a40 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
24a50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
24a60 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
24a70 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
24a80 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
24a90 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
24aa0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
24ab0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
24ac0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
24ad0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
24ae0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
24af0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
24b00 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
24b10 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
24b20 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
24b30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
24b40 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
24b50 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
24b60 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
24b70 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
24b80 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
24b90 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
24ba0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
24bb0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
24bc0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
24bd0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
24be0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
24bf0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
24c00 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
24c10 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
24c20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
24c30 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
24c40 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
24c50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
24c60 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
24c70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
24c80 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
24c90 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
24ca0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
24cb0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
24cc0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
24cd0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
24ce0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
24cf0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
24d00 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
24d10 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
24d20 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
24d30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
24d40 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
24d50 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
24d60 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
24d70 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
24d80 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
24d90 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
24da0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
24db0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
24dc0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
24dd0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
24de0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
24df0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
24e00 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
24e10 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
24e20 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
24e30 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
24e40 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
24e50 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
24e60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
24e70 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
24e80 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
24e90 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
24ea0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
24eb0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
24ec0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
24ed0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
24ee0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
24ef0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
24f00 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
24f10 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
24f20 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
24f30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
24f40 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
24f50 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
24f60 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
24f70 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
24f80 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
24f90 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
24fa0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
24fb0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
24fc0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
24fd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
24fe0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
24ff0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c ** ^(On windows,
25000 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
25010 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
25020 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
25030 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
25040 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
25050 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 ).)^.**.** [[cor
25060 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
25070 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
25080 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
25090 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
250a0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
250b0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
250c0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
250d0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
250e0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
250f0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
25100 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
25110 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 QLite and its bu
25120 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 ilt-in [VFSes] i
25130 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 nterpret the.**
25140 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 following query
25150 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a parameters:.**.*
25160 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
25170 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 <b>vfs</b>: ^Th
25180 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 e "vfs" paramete
25190 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f r may be used to
251a0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d specify the nam
251b0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 e of.** a VF
251c0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 S object that pr
251d0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 ovides the opera
251e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
251f0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c rface that shoul
25200 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 d.** be used
25210 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
25220 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 atabase file on
25230 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f disk. ^If this o
25240 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a ption is set to.
25250 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 ** an empty
25260 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 string the defau
25270 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 lt VFS object is
25280 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 used. ^Specifyi
25290 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a ng an unknown.**
252a0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 VFS is an e
252b0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 rror. ^If sqlite
252c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
252d0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 sed and the vfs
252e0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
252f0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 present, then t
25300 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 he VFS specified
25310 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 by the option t
25320 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 akes precedence
25330 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 over.** the
25340 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
25350 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
25360 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
25370 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
25380 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c <li> <b>mode<
25390 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 /b>: ^(The mode
253a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
253b0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
253c0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 ro", "rw",.**
253d0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d "rwc", or "mem
253e0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 ory". Attempting
253f0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e to set it to an
25400 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 y other value is
25410 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 .** an error
25420 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 )^. .** ^If
25430 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 "ro" is specifie
25440 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 d, then the data
25450 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
25460 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a or read-only .**
25470 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 access, jus
25480 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c t as if the [SQL
25490 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
254a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e Y] flag had been
254b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 set in the .**
254c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 third argume
254d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
254e0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 en_v2(). ^If the
254f0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 mode option is
25500 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 set to .** "
25510 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 rw", then the da
25520 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
25530 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 for read-write
25540 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 (but not create)
25550 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
25560 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 as if SQLITE_OP
25570 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 EN_READWRITE (bu
25580 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 t not SQLITE_OPE
25590 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a N_CREATE) had .*
255a0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 * been set.
255b0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 ^Value "rwc" is
255c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
255d0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 tting both .**
255e0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 SQLITE_OPEN_R
255f0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c EADWRITE and SQL
25600 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e ITE_OPEN_CREATE.
25610 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f ^If the mode o
25620 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
25630 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 set to "memory"
25640 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d then a pure [in-
25650 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d memory database]
25660 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 that never read
25670 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 s.** or writ
25680 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 es from disk is
25690 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 used. ^It is an
256a0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
256b0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 a value for.**
256c0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 the mode par
256d0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c ameter that is l
256e0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
256f0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
25700 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 ied by.** th
25710 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 e flags passed i
25720 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
25730 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
25740 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
25750 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
25760 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
25770 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
25780 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
25790 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
257a0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
257b0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
257c0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
257d0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
257e0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
257f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
25800 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
25810 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
25820 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
25830 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25840 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
25850 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
25860 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
25870 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
25880 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
25890 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
258a0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
258b0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
258c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
258d0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
258e0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
258f0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
25900 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
25910 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
25920 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
25930 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 or requested by
25940 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 setting.** S
25950 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
25960 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 TECACHE or SQLIT
25970 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
25980 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 HE flag..**.**
25990 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e <li> <b>psow</b>
259a0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 : ^The psow para
259b0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 meter indicates
259c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
259d0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 he.** [power
259e0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 safe overwrite]
259f0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 property does or
25a00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 does not apply
25a10 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 to the.** st
25a20 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 orage media on w
25a30 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 hich the databas
25a40 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a e file resides..
25a50 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e **.** <li> <b>n
25a60 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 olock</b>: ^The
25a70 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 nolock parameter
25a80 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
25a90 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ery parameter.**
25aa0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 which if se
25ab0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 t disables file
25ac0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 locking in rollb
25ad0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 ack journal mode
25ae0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 s. This.**
25af0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 is useful for ac
25b00 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 cessing a databa
25b10 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 se on a filesyst
25b20 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 em that does not
25b30 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 .** support
25b40 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f locking. Cautio
25b50 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 n: Database cor
25b60 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ruption might re
25b70 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 sult if two.**
25b80 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 or more proce
25b90 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 sses write to th
25ba0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
25bb0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 and any one of t
25bc0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 hose.** proc
25bd0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 esses uses noloc
25be0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e k=1..**.** <li>
25bf0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 <b>immutable</b
25c00 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c >: ^The immutabl
25c10 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 e parameter is a
25c20 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a boolean query.*
25c30 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 * parameter
25c40 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 that indicates t
25c50 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
25c60 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 file is stored
25c70 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f on.** read-o
25c80 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 nly media. ^Whe
25c90 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 n immutable is s
25ca0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d et, SQLite assum
25cb0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 es that the.**
25cc0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 database file
25cd0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
25ce0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 ed, even by a pr
25cf0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 ocess with highe
25d00 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 r.** privile
25d10 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 ge, and so the d
25d20 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
25d30 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 d read-only and
25d40 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 all locking.**
25d50 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 and change de
25d60 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 tection is disab
25d70 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 led. Caution: S
25d80 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 etting the immut
25d90 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 able.** prop
25da0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 erty on a databa
25db0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 se file that doe
25dc0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 s in fact change
25dd0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 can result.**
25de0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 in incorrect
25df0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e query results an
25e00 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 d/or [SQLITE_COR
25e10 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a RUPT] errors..**
25e20 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b See also: [
25e30 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
25e40 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 UTABLE]..**
25e50 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a .** </ul>.**.*
25e60 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
25e70 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
25e80 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
25e90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
25ea0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
25eb0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
25ec0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
25ed0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
25ee0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
25ef0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
25f00 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
25f10 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
25f20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
25f30 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
25f40 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
25f50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
25f60 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
25f70 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
25f80 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
25f90 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
25fa0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
25fb0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
25fc0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
25fd0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
25fe0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
25ff0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
26000 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
26010 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
26020 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
26030 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
26040 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
26050 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
26060 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
26070 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
26080 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
26090 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
260a0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
260b0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
260c0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
260d0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
260e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
260f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
26100 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
26110 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
26120 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
26130 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
26140 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
26150 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
26160 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
26170 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
26180 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
26190 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
261a0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
261b0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
261c0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
261d0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
261e0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
261f0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
26200 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
26210 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
26220 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
26230 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
26240 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
26250 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
26260 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
26270 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
26280 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
26290 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
262a0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
262b0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
262c0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
262d0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
262e0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
262f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
26300 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
26310 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
26320 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26330 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
26340 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
26350 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
26360 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
26370 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
26380 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
26390 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
263a0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
263b0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
263c0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
263d0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
263e0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
263f0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
26400 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
26410 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 =unix-dotfile <t
26420 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f d>.** O
26430 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f pen file "/home/
26440 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 fred/data.db". U
26450 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 se the special V
26460 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 FS "unix-dotfile
26470 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ".** th
26480 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 at uses dot-file
26490 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f s in place of po
264a0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 six advisory loc
264b0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 king..** <tr><td
264c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
264d0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 ode=readonly <td
264e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
264f0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e n error. "readon
26500 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c ly" is not a val
26510 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 id option for th
26520 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 e "mode" paramet
26530 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
26540 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 **.** ^URI hexad
26550 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
26560 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 quences (%HH) ar
26570 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 e supported with
26580 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a in the path and.
26590 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 ** query compone
265a0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 nts of a URI. A
265b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
265c0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 pe sequence cons
265d0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 ists of a.** per
265e0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 cent sign - "%"
265f0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 - followed by ex
26600 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 actly two hexade
26610 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a cimal digits .**
26620 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f specifying an o
26630 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 ctet value. ^Bef
26640 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 ore the path or
26650 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
26660 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c of a.** URI fil
26670 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 ename are interp
26680 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 reted, they are
26690 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 encoded using UT
266a0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 F-8 and all .**
266b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
266c0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 pe sequences rep
266d0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c laced by a singl
266e0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e e byte containin
266f0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 g the.** corresp
26700 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 onding octet. If
26710 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 this process ge
26720 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c nerates an inval
26730 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e id UTF-8 encodin
26740 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 g,.** the result
26750 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
26760 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
26770 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
26780 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
26790 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
267a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
267b0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
267c0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
267d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
267e0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
267f0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
26800 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
26810 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
26820 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
26830 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
26840 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
26850 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
26860 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
26870 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
26880 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
26890 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
268a0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
268b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
268c0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
268d0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
268e0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
268f0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
26900 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
26910 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
26920 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
26930 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 2(). Otherwise,
26940 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
26950 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
26960 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
26970 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
26980 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fail..**.** See
26990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
269a0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a temp_directory].
269b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
269c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
269d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
269e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
269f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
26a00 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
26a10 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
26a20 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
26a30 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
26a40 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
26a50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
26a60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
26a70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a sqlite3_open16(.
26a80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 const void *fi
26a90 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
26aa0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
26ab0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c UTF-16) */. sql
26ac0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
26ad0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
26ae0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
26af0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
26b00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
26b10 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 L sqlite3_open_v
26b20 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
26b30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
26b40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
26b50 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
26b60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
26b70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
26b80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
26b90 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
26ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
26bb0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
26bc0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
26bd0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
26be0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
26bf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
26c00 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 I3REF: Obtain Va
26c10 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 lues For URI Par
26c20 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 ameters.**.** Th
26c30 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 ese are utility
26c40 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c routines, useful
26c50 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e to VFS implemen
26c60 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 tations, that ch
26c70 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 eck.** to see if
26c80 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
26c90 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 was a URI that
26ca0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 contained a spec
26cb0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 ific query .** p
26cc0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 arameter, and if
26cd0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 so obtains the
26ce0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 value of that qu
26cf0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ery parameter..*
26d00 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 *.** If F is the
26d10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
26d20 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 me pointer passe
26d30 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
26d40 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a () method of .**
26d50 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 a VFS implement
26d60 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 ation when the f
26d70 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
26d80 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e o xOpen() has on
26d90 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 e or .** more of
26da0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
26db0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 N_URI] or [SQLIT
26dc0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 E_OPEN_MAIN_DB]
26dd0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 bits set and.**
26de0 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 P is the name of
26df0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d the query param
26e00 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 eter, then.** sq
26e10 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
26e20 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
26e30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
26e40 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 e P.** parameter
26e50 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 if it exists or
26e60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
26e70 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 if P does not ap
26e80 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 pear as a .** qu
26e90 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e ery parameter on
26ea0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 F. If P is a q
26eb0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
26ec0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 f F.** has no ex
26ed0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 plicit value, th
26ee0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
26ef0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
26f00 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 turns.** a point
26f10 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 er to an empty s
26f20 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
26f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
26f40 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
26f50 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ine assumes that
26f60 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a P is a boolean.
26f70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 ** parameter and
26f80 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
26f90 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 ) or false (0) a
26fa0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 ccording to the
26fb0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 value.** of P.
26fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
26fd0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
26fe0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
26ff0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a rue (1) if the.*
27000 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 * value of query
27010 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
27020 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 one of "yes", "t
27030 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e rue", or "on" in
27040 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 any.** case or
27050 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
27060 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a ins with a non-z
27070 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 ero number. The
27080 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 .** sqlite3_uri
27090 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
270a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 routines returns
270b0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 false (0) if th
270c0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 e value of.** qu
270d0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
270e0 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 is one of "no",
270f0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 "false", or "off
27100 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 " in any case or
27110 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 .** if the value
27120 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
27130 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 umeric zero. If
27140 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 P is not a quer
27150 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
27160 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 n F or if the va
27170 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 lue of P is does
27180 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f not match any o
27190 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 f the.** above,
271a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
271b0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
271c0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a returns (B!=0)..
271d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
271e0 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 3_uri_int64(F,P,
271f0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 D) routine conve
27200 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rts the value of
27210 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d P into a.** 64-
27220 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
27230 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 er and returns t
27240 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 hat integer, or
27250 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a D if P does not.
27260 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 ** exist. If th
27270 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
27280 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
27290 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c than an integer,
272a0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 then.** zero is
272b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a returned..** .*
272c0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c * If F is a NULL
272d0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 pointer, then s
272e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
272f0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
27300 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 s NULL and.** sq
27310 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
27320 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
27330 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 B. If F is not
27340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
27350 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 and.** is not a
27360 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 database file pa
27370 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 thname pointer t
27380 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 hat SQLite passe
27390 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
273a0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 .** VFS method,
273b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
273c0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e r of this routin
273d0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 e is undefined a
273e0 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 nd probably.** u
273f0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 ndesirable..*/.S
27400 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
27410 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
27420 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 CALL sqlite3_uri
27430 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 _parameter(const
27440 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
27450 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
27460 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 aram);.SQLITE_AP
27470 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
27480 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 CALL sqlite3_uri
27490 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 _boolean(const c
274a0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 har *zFile, cons
274b0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 t char *zParam,
274c0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 int bDefault);.S
274d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
274e0 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 3_int64 SQLITE_S
274f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 TDCALL sqlite3_u
27500 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 ri_int64(const c
27510 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 har*, const char
27520 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
27530 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
27540 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 REF: Error Codes
27550 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a And Messages.**
27560 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
27570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
27580 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 ost recent sqlit
27590 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 e3_* API call as
275a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a sociated with .*
275b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
275c0 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 ection] D failed
275d0 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
275e0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e e3_errcode(D) in
275f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 terface.** retur
27600 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b ns the numeric [
27610 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
27620 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
27630 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a code] for that.
27640 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 ** API call..**
27650 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
27660 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 nt API call was
27670 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 successful,.** t
27680 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
27690 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
276a0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
276b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 ndefined..** ^Th
276c0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
276d0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
276e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
276f0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
27700 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
27710 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
27720 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
27730 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
27740 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
27750 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
27760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
27770 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
27780 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
27790 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
277a0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
277b0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
277c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
277d0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
277e0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
277f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
27800 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
27810 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
27820 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
27830 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
27840 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
27850 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
27860 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
27870 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
27880 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
27890 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
278a0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
278b0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
278c0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
278d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
278e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
278f0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
27900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27910 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 e3_errstr() inte
27920 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
27930 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 e English-langua
27940 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 ge text.** that
27950 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 describes the [r
27960 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 esult code], as
27970 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f UTF-8..** ^(Memo
27980 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
27990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
279a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
279b0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 nternally.** and
279c0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 must not be fre
279d0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
279e0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 ation)^..**.** W
279f0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
27a00 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
27a10 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
27a20 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
27a30 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
27a40 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
27a50 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
27a60 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
27a70 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
27a80 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
27a90 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
27aa0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
27ab0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
27ac0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
27ad0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
27ae0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
27af0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
27b00 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
27b10 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
27b20 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
27b30 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
27b40 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
27b50 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
27b60 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
27b70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
27b80 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
27b90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
27ba0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
27bb0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
27bc0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
27bd0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
27be0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
27bf0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
27c00 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
27c10 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
27c20 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
27c30 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
27c40 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
27c50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
27c60 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
27c70 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
27c80 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
27c90 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
27ca0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
27cb0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
27cc0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
27cd0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
27ce0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
27cf0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
27d00 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
27d10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
27d20 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
27d30 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 L sqlite3_errcod
27d40 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
27d50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
27d60 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
27d70 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
27d80 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
27d90 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
27da0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
27db0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
27dc0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 e3_errmsg(sqlite
27dd0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 3*);.SQLITE_API
27de0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
27df0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
27e00 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 e3_errmsg16(sqli
27e10 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 te3*);.SQLITE_AP
27e20 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
27e30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
27e40 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 ite3_errstr(int)
27e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
27e60 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
27e70 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 ement Object.**
27e80 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 KEYWORDS: {prepa
27e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b red statement} {
27ea0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27eb0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e nts}.**.** An in
27ec0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
27ed0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
27ee0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 a single SQL st
27ef0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 atement that.**
27f00 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 has been compile
27f10 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f d into binary fo
27f20 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 rm and is ready
27f30 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e to be evaluated.
27f40 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 .**.** Think of
27f50 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
27f60 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 nt as a separate
27f70 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 computer progra
27f80 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 m. The.** origi
27f90 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 nal SQL text is
27fa0 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 source code. A
27fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27fc0 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 nt object .** is
27fd0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 the compiled ob
27fe0 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 ject code. All
27ff0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 SQL must be conv
28000 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 erted into a.**
28010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28020 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e nt before it can
28030 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 be run..**.** T
28040 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 he life-cycle of
28050 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
28060 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 ement object usu
28070 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 ally goes like t
28080 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
28090 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
280a0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
280b0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 ement object usi
280c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
280d0 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c are_v2()]..** <l
280e0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
280f0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 o [parameters] u
28100 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
28110 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
28120 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
28130 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
28140 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
28150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
28160 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
28170 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
28180 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
28190 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
281a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
281b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
281c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
281d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
281e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
281f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
28200 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
28210 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
28220 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 ..** </ol>.*/.ty
28230 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
28240 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
28250 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
28260 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
28270 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 e Limits.** METH
28280 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
28290 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 * ^(This interfa
282a0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 ce allows the si
282b0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f ze of various co
282c0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c nstructs to be l
282d0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 imited.** on a c
282e0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e onnection by con
282f0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 nection basis.
28300 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
28310 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 ter is the.** [d
28320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28330 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 on] whose limit
28340 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 is to be set or
28350 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a queried. The.**
28360 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
28370 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 r is one of the
28380 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 [limit categorie
28390 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 s] that define a
283a0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e .** class of con
283b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 structs to be si
283c0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 ze limited. The
283d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
283e0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c is the.** new l
283f0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f imit for that co
28400 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a nstruct.)^.**.**
28410 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d ^If the new lim
28420 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
28430 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
28440 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
28450 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c .** ^(For each l
28460 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 imit category SQ
28470 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 LITE_LIMIT_<i>NA
28480 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 ME</i> there is
28490 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 a .** [limits |
284a0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
284b0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 ].** set at comp
284c0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 ile-time by a C
284d0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
284e0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 ro called.** [li
284f0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 mits | SQLITE_MA
28500 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a X_<i>NAME</i>]..
28510 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
28520 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
28530 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
28540 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 X_".))^.** ^Atte
28550 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 mpts to increase
28560 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 a limit above i
28570 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f ts hard upper bo
28580 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e und are.** silen
28590 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f tly truncated to
285a0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 the hard upper
285b0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 bound..**.** ^Re
285c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
285d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c her or not the l
285e0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 imit was changed
285f0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 , the .** [sqlit
28600 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 e3_limit()] inte
28610 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
28620 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 e prior value of
28630 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e the limit..** ^
28640 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 Hence, to find t
28650 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
28660 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 of a limit with
28670 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c out changing it,
28680 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b .** simply invok
28690 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 e this interface
286a0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 with the third
286b0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f parameter set to
286c0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 -1..**.** Run-t
286d0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 ime limits are i
286e0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
286f0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 in applications
28700 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 that manage.** b
28710 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e oth their own in
28720 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 ternal database
28730 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 and also databas
28740 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 es that are cont
28750 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 rolled.** by unt
28760 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 rusted external
28770 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 sources. An exa
28780 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e mple application
28790 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 might be a.** w
287a0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 eb browser that
287b0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 has its own data
287c0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e bases for storin
287d0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a g history and.**
287e0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 separate databa
287f0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 ses controlled b
28800 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 y JavaScript app
28810 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f lications downlo
28820 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 aded.** off the
28830 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 Internet. The i
28840 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
28850 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 s can be given t
28860 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 he.** large, def
28870 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 ault limits. Da
28880 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 tabases managed
28890 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 by external sour
288a0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 ces can.** be gi
288b0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 ven much smaller
288c0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 limits designed
288d0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 to prevent a de
288e0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a nial of service.
288f0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 ** attack. Deve
28900 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 lopers might als
28910 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 o want to use th
28920 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
28930 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 uthorizer()].**
28940 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 interface to fur
28950 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 ther control unt
28960 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 rusted SQL. The
28970 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 size of the dat
28980 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 abase.** created
28990 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 by an untrusted
289a0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 script can be c
289b0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 ontained using t
289c0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f he.** [max_page_
289d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e count] [PRAGMA].
289e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 .**.** New run-t
289f0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ime limit catego
28a00 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 ries may be adde
28a10 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
28a20 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ases..*/.SQLITE_
28a30 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
28a40 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c TDCALL sqlite3_l
28a50 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
28a60 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
28a70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
28a80 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
28a90 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
28aa0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
28ab0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
28ac0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
28ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
28ae0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
28af0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
28b00 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
28b10 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
28b20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
28b30 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
28b40 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
28b50 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
28b60 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
28b70 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
28b80 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
28b90 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
28ba0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
28bb0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
28bc0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
28bd0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
28be0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
28bf0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
28c00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
28c10 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
28c20 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
28c30 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
28c40 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
28c50 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e w, in bytes.<dd>
28c60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
28c70 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
28c80 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
28c90 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
28ca0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
28cb0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
28cc0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
28cd0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e ement, in bytes.
28ce0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
28cf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
28d00 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 UMN]] ^(<dt>SQLI
28d10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
28d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
28d30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
28d40 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
28d50 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
28d60 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
28d70 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
28d80 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
28d90 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
28da0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
28db0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
28dc0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
28dd0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
28de0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
28df0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
28e00 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
28e10 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
28e20 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
28e30 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
28e40 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
28e50 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
28e60 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a sion.</dd>)^.**.
28e70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
28e80 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
28e90 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
28ea0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
28eb0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c SELECT</dt>.** <
28ec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
28ed0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
28ee0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c n a compound SEL
28ef0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f ECT statement.</
28f00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
28f10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
28f20 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 OP]] ^(<dt>SQLIT
28f30 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
28f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
28f50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
28f60 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
28f70 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
28f80 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
28f90 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
28fa0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
28fb0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 t. This limit i
28fc0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a s not currently.
28fd0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f ** enforced, tho
28fe0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 ugh that might b
28ff0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 e added in some
29000 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
29010 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 f.** SQLite.</dd
29020 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
29030 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
29040 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 N_ARG]] ^(<dt>SQ
29050 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
29060 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
29070 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
29080 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
29090 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
290a0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
290b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 [[SQLITE_LIMIT_A
290c0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e TTACHED]] ^(<dt>
290d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
290e0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
290f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
29100 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
29110 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
29120 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a ases].)^</dd>.**
29130 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
29140 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
29150 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 LENGTH]].** ^(<d
29160 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
29170 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
29180 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
29190 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
291a0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
291b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
291c0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
291d0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
291e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
291f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
29200 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a ABLE_NUMBER]].**
29210 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29220 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
29230 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
29240 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
29250 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
29260 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
29270 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
29280 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29290 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
292a0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
292b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
292c0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a ER_DEPTH</dt>.**
292d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
292e0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 depth of recurs
292f0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 ion for triggers
29300 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
29310 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f [SQLITE_LIMIT_WO
29320 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e RKER_THREADS]] ^
29330 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
29340 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
29350 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
29360 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
29370 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 of auxiliary wor
29380 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 ker threads that
29390 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 a single.** [pr
293a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
293b0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 ] may start.</dd
293c0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a >)^.** </dl>.*/.
293d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
293e0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
293f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
29400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29410 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
29420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29430 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
29440 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
29450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29460 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
29470 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
29480 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
29490 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
294a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
294b0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
294c0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
294d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
294e0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
294f0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
29500 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
29510 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
29520 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
29530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
29540 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
29550 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
29560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
29570 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
29580 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
29590 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
295a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
295b0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
295c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
295d0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
295e0 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 10.#defi
295f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29600 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 WORKER_THREADS
29610 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 11../*.
29620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
29630 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
29640 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
29650 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
29660 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
29670 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
29680 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
29690 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
296a0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
296b0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
296c0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
296d0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
296e0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
296f0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
29700 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
29710 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
29720 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
29730 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
29740 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
29750 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
29760 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
29770 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
29780 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
29790 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
297a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
297b0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
297c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
297d0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
297e0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
297f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
29800 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
29810 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
29820 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
29830 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
29840 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
29850 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
29860 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
29870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29880 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
29890 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
298a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
298b0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
298c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
298d0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
298e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
298f0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
29900 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a negative, then z
29910 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
29920 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
29930 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
29940 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 ^If nByte is pos
29950 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 itive, then it i
29960 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
29970 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 of bytes read fr
29980 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 om zSql. ^If nB
29990 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 yte is zero, the
299a0 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a n no prepared.**
299b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 statement is ge
299c0 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 nerated..** If t
299d0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 he caller knows
299e0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
299f0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
29a00 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
29a10 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 .** there is a s
29a20 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 mall performance
29a30 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 advantage to pa
29a40 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 ssing an nByte p
29a50 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a arameter that.**
29a60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
29a70 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
29a80 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
29a90 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
29aa0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
29ab0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a or..**.** ^If pz
29ac0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
29ad0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 then *pzTail is
29ae0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
29af0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 o the first byte
29b00 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 .** past the end
29b10 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 of the first SQ
29b20 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a L statement in z
29b30 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 Sql. These rout
29b40 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d ines only.** com
29b50 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 pile the first s
29b60 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
29b70 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 , so *pzTail is
29b80 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
29b90 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 .** what remains
29ba0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a uncompiled..**.
29bb0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c ** ^*ppStmt is l
29bc0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
29bd0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
29be0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29bf0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
29c00 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
29c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
29c20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e ^If there is an
29c30 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
29c40 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
29c50 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 L. ^If the inpu
29c60 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
29c70 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
29c80 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
29c90 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
29ca0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
29cb0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
29cc0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
29cd0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
29ce0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
29cf0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
29d00 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
29d10 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
29d20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
29d30 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
29d40 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
29d50 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
29d60 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
29d70 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c .** ^On success,
29d80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 the sqlite3_pre
29d90 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 pare() family of
29da0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
29db0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a [SQLITE_OK];.**
29dc0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
29dd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
29de0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
29df0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
29e00 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
29e10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
29e20 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
29e30 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
29e40 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
29e50 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
29e60 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
29e70 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
29e80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
29e90 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
29ea0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
29eb0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e couraged..** ^In
29ec0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
29ed0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
29ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
29ef0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
29f00 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
29f10 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
29f20 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
29f30 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
29f40 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
29f50 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
29f60 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
29f70 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
29f80 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e e differently in
29f90 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a three ways:.**.
29fa0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
29fb0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
29fc0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
29fd0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
29fe0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
29ff0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
2a000 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
2a010 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
2a020 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
2a030 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
2a040 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
2a050 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
2a060 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
2a070 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c As many as [SQL
2a080 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 ITE_MAX_SCHEMA_R
2a090 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 ETRY].** retries
2a0a0 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f will occur befo
2a0b0 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 re sqlite3_step(
2a0c0 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 ) gives up and r
2a0d0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e eturns an error.
2a0e0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
2a0f0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e <li>.** ^When an
2a100 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
2a110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2a120 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
2a130 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
2a140 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
2a150 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
2a160 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 ror codes]. ^Th
2a170 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
2a180 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 r was that.** [s
2a190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
2a1a0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e ould only return
2a1b0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 a generic [SQLI
2a1c0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 TE_ERROR] result
2a1d0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 code.** and the
2a1e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 application wou
2a1f0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
2a200 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
2a210 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2a220 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 )].** in order t
2a230 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
2a240 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
2a250 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
2a260 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
2a270 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
2a280 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
2a290 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
2a2a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
2a2b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
2a2c0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
2a2d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 >.** ^If the spe
2a2e0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e cific value boun
2a2f0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 d to [parameter
2a300 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
2a310 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 ] in the .** WHE
2a320 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 RE clause might
2a330 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 influence the ch
2a340 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
2a350 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 an for a stateme
2a360 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 nt,.** then the
2a370 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
2a380 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2a390 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 recompiled, as i
2a3a0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
2a3b0 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 .** a schema ch
2a3c0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 ange, on the fir
2a3d0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 st [sqlite3_ste
2a3e0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
2a3f0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a ing any change.*
2a400 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2a410 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
2a420 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 ndings] of that
2a430 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
2a440 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 ^The specific v
2a450 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c alue of WHERE-cl
2a460 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d ause [parameter]
2a470 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2a480 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 the .** choice
2a490 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 of query plan if
2a4a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
2a4b0 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 s the left-hand
2a4c0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d side of a [LIKE]
2a4d0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 .** or [GLOB] op
2a4e0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 erator or if the
2a4f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f parameter is co
2a500 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 mpared to an ind
2a510 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 exed column.** a
2a520 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 nd the [SQLITE_E
2a530 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d NABLE_STAT3] com
2a540 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
2a550 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 is enabled..**
2a560 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
2a570 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a580 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2a5a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2a5b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2a5c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2a5d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2a5e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2a5f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2a600 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
2a610 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2a620 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2a630 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2a640 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2a650 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2a660 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2a670 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2a680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2a690 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
2a6a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2a6b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2a6c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
2a6d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2a6e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2a6f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2a700 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2a710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2a720 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2a730 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2a740 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2a750 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2a760 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
2a770 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2a780 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2a790 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2a7a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2a7b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2a7c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2a7d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2a7e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2a7f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
2a800 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2a810 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2a820 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
2a830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2a840 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2a850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
2a860 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2a870 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2a880 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2a890 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
2a8a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2a8b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2a8c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
2a8d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2a8e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2a8f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2a900 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2a910 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2a920 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2a930 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2a940 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
2a950 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
2a960 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2a970 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2a980 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
2a990 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2a9a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2a9b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a9c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2a9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2a9e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2a9f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2aa00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2aa10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2aa20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
2aa30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2aa40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2aa50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2aa60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2aa70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2aa80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2aa90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2aaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2aab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2aac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2aad0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2aae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2aaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ab00 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
2ab10 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d atement SQL.** M
2ab20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2ab30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 tmt.**.** ^This
2ab40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
2ab50 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
2ab60 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
2ab70 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
2ab80 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
2ab90 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
2aba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2abb0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
2abc0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
2abd0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
2abe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2abf0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
2ac00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2ac10 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2ac20 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
2ac30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2ac40 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
2ac50 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2ac60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ac70 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
2ac80 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 SQL Statement Wr
2ac90 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 ites The Databas
2aca0 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
2acb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2acc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2acd0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e t_readonly(X) in
2ace0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2acf0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 true (non-zero)
2ad00 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 if.** and only i
2ad10 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 f the [prepared
2ad20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b statement] X mak
2ad30 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 es no direct cha
2ad40 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 nges to.** the c
2ad50 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 ontent of the da
2ad60 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a tabase file..**.
2ad70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 ** Note that [ap
2ad80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2ad90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2ada0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 or.** [virtual
2adb0 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 tables] might ch
2adc0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
2add0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 e indirectly as
2ade0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 a side effect.
2adf0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c .** ^(For exampl
2ae00 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 e, if an applica
2ae10 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 tion defines a f
2ae20 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 unction "eval()"
2ae30 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 that .** calls
2ae40 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
2ae50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f , then the follo
2ae60 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 wing SQL stateme
2ae70 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e nt would.** chan
2ae80 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2ae90 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 file through sid
2aea0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a e-effects:.**.**
2aeb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
2aec0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 e>.** SELECT
2aed0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f eval('DELETE FRO
2aee0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a M t1') FROM t2;.
2aef0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
2af00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 quote>.**.** But
2af10 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 because the [SE
2af20 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
2af30 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
2af40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2af50 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 e.** directly, s
2af60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2af70 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 only() would sti
2af80 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 ll return true.)
2af90 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 ^.**.** ^Transac
2afa0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 tion control sta
2afb0 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 tements such as
2afc0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 [BEGIN], [COMMIT
2afd0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a ], [ROLLBACK],.*
2afe0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 * [SAVEPOINT], a
2aff0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 nd [RELEASE] cau
2b000 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f se sqlite3_stmt_
2b010 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
2b020 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 turn true,.** si
2b030 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e nce the statemen
2b040 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f ts themselves do
2b050 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f not actually mo
2b060 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
2b070 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 e but.** rather
2b080 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 they control the
2b090 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 timing of when
2b0a0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 other statements
2b0b0 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 modify the .**
2b0c0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 database. ^The
2b0d0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 [ATTACH] and [DE
2b0e0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 TACH] statements
2b0f0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 also cause.** s
2b100 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2b110 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
2b120 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 true since, whi
2b130 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 le those stateme
2b140 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 nts.** change th
2b150 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
2b160 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f of a database co
2b170 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 nnection, they d
2b180 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 o not make .** c
2b190 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f hanges to the co
2b1a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 ntent of the dat
2b1b0 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 abase files on d
2b1c0 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 isk..*/.SQLITE_A
2b1d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b1e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 DCALL sqlite3_st
2b1f0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
2b200 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2b210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b220 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2b230 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2b240 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
2b250 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 set.** METHOD: s
2b260 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2b270 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2b280 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 tmt_busy(S) inte
2b290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
2b2a0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
2b2b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2b2c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 d statement] S h
2b2d0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 as been stepped
2b2e0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 at least once us
2b2f0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
2b300 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 _step(S)] but ha
2b310 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f s neither run to
2b320 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 completion (ret
2b330 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
2b340 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c _DONE] from [sql
2b350 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e ite3_step(S)]) n
2b360 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 or.** been reset
2b370 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2b380 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 reset(S)]. ^The
2b390 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2b3a0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 sy(S).** interfa
2b3b0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 ce returns false
2b3c0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 if S is a NULL
2b3d0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 pointer. If S i
2b3e0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c s not a .** NULL
2b3f0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 pointer and is
2b400 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f not a pointer to
2b410 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 a valid [prepar
2b420 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2b430 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 object, then th
2b440 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2b450 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
2b460 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
2b470 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2b480 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2b490 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f ed in combinatio
2b4a0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f n [sqlite3_next_
2b4b0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f stmt()].** to lo
2b4c0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 cate all prepare
2b4d0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
2b4e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 ociated with a d
2b4f0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e atabase .** conn
2b500 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 ection that are
2b510 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 in need of being
2b520 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 reset. This ca
2b530 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f n be used,.** fo
2b540 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 r example, in di
2b550 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 agnostic routine
2b560 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 s to search for
2b570 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 prepared .** sta
2b580 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 tements that are
2b590 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 holding a trans
2b5a0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a action open..*/.
2b5b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2b5c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2b5d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
2b5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2b5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b600 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 Dynamically Typ
2b610 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a ed Value Object.
2b620 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
2b630 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2b640 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 value} {unprotec
2b650 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2b660 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 e}.**.** SQLite
2b670 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 uses the sqlite3
2b680 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f _value object to
2b690 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 represent all v
2b6a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 alues.** that ca
2b6b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 n be stored in a
2b6c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e database table.
2b6d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e SQLite uses dyn
2b6e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 amic typing.** f
2b6f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 or the values it
2b700 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 stores. ^Value
2b710 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 s stored in sqli
2b720 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2b730 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 s.** can be inte
2b740 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 gers, floating p
2b750 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 oint values, str
2b760 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 ings, BLOBs, or
2b770 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 NULL..**.** An s
2b780 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2b790 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 ect may be eithe
2b7a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 r "protected" or
2b7b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a "unprotected"..
2b7c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 ** Some interfac
2b7d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f es require a pro
2b7e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2b7f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 alue. Other int
2b800 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 erfaces.** will
2b810 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 accept either a
2b820 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 protected or an
2b830 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2b840 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 te3_value..** Ev
2b850 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 ery interface th
2b860 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 at accepts sqlit
2b870 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e e3_value argumen
2b880 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ts specifies.**
2b890 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
2b8a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f t requires a pro
2b8b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2b8c0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 alue. The.** [s
2b8d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
2b8e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 ()] interface ca
2b8f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e n be used to con
2b900 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a struct a new .**
2b910 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2b920 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e e3_value from an
2b930 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
2b940 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a ite3_value..**.*
2b950 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f * The terms "pro
2b960 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 tected" and "unp
2b970 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 rotected" refer
2b980 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f to whether or no
2b990 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 t.** a mutex is
2b9a0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e held. An intern
2b9b0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 al mutex is held
2b9c0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 for a protected
2b9d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
2b9e0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 e object but no
2b9f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
2ba00 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
2ba10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
2ba20 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 e object. If SQ
2ba30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
2ba40 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 to be single-th
2ba50 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 readed.** (with
2ba60 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
2ba70 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b FE=0] and with [
2ba80 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
2ba90 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 fe()] returning
2baa0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 0).** or if SQLi
2bab0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 te is run in one
2bac0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 of reduced mute
2bad0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c x modes .** [SQL
2bae0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
2baf0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c ETHREAD] or [SQL
2bb00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
2bb10 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 THREAD].** then
2bb20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 there is no dist
2bb30 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
2bb40 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
2bb50 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
2bb60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2bb70 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 ts and they can
2bb80 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 be used intercha
2bb90 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 ngeably. Howeve
2bba0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 r,.** for maximu
2bbb0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 m code portabili
2bbc0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ty it is recomme
2bbd0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
2bbe0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 ations.** still
2bbf0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
2bc00 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
2bc10 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
2bc20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2bc30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
2bc40 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
2bc50 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
2bc60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2bc70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2bc80 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 s that are passe
2bc90 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 d as parameters
2bca0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c into the.** impl
2bcb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 ementation of [a
2bcc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2bcd0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
2bce0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e ] are protected.
2bcf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2bd00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 _value object re
2bd10 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2bd30 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 ue()] is unprote
2bd40 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 cted..** Unprote
2bd50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2bd60 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f ue objects may o
2bd70 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
2bd80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2bd90 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ult_value()] and
2bda0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
2bdb0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 alue()]..** The
2bdc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
2bdd0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 lob | sqlite3_va
2bde0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 lue_type()] fami
2bdf0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 ly of.** interfa
2be00 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 ces require prot
2be10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2be20 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a lue objects..*/.
2be30 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
2be40 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
2be50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2be60 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 F: SQL Function
2be70 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a Context Object.*
2be80 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
2be90 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
2bea0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
2beb0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
2bec0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
2bed0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e ntext object. ^
2bee0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
2bef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
2bf00 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 object.** is alw
2bf10 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 ays first parame
2bf20 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 ter to [applicat
2bf30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2bf40 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 functions]..** T
2bf50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2bf60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2bf70 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2bf80 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 on will pass thi
2bf90 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 s.** pointer thr
2bfa0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 ough into calls
2bfb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
2bfc0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 lt_int | sqlite3
2bfd0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b _result()],.** [
2bfe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2bff0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 e_context()], [s
2c000 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
2c010 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2c020 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
2c030 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f le()], [sqlite3_
2c040 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a get_auxdata()],.
2c050 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 ** and/or [sqlit
2c060 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
2c070 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
2c080 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e ruct sqlite3_con
2c090 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e text sqlite3_con
2c0a0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 text;../*.** CAP
2c0b0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 I3REF: Binding V
2c0c0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 alues To Prepare
2c0d0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 d Statements.**
2c0e0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 KEYWORDS: {host
2c0f0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 parameter} {host
2c100 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f parameters} {ho
2c110 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
2c120 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 e}.** KEYWORDS:
2c130 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 {SQL parameter}
2c140 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d {SQL parameters}
2c150 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 {parameter bind
2c160 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ing}.** METHOD:
2c170 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2c180 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 ** ^(In the SQL
2c190 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 statement text i
2c1a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
2c1b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
2c1c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c nd its variants,
2c1d0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 .** literals may
2c1e0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 be replaced by
2c1f0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 a [parameter] th
2c200 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f at matches one o
2c210 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 f following.** t
2c220 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 emplates:.**.**
2c230 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a <ul>.** <li> ?.
2c240 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a ** <li> ?NNN.**
2c250 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c <li> :VVV.** <
2c260 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 li> @VVV.** <li
2c270 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e > $VVV.** </ul>
2c280 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 .**.** In the te
2c290 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e mplates above, N
2c2a0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e NN represents an
2c2b0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c integer literal
2c2c0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 ,.** and VVV rep
2c2d0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 resents an alpha
2c2e0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 numeric identifi
2c2f0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 er.)^ ^The valu
2c300 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 es of these.** p
2c310 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 arameters (also
2c320 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 called "host par
2c330 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 ameter names" or
2c340 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 "SQL parameters
2c350 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 ").** can be set
2c360 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
2c370 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
2c380 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 ines defined her
2c390 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 e..**.** ^The fi
2c3a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
2c3b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2c3c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 _*() routines is
2c3d0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 always.** a poi
2c3e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
2c3f0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
2c400 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a t returned from.
2c410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2c420 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 are_v2()] or its
2c430 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a variants..**.**
2c440 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ^The second arg
2c450 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
2c460 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 ex of the SQL pa
2c470 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 rameter to be se
2c480 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d t..** ^The leftm
2c490 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ost SQL paramete
2c4a0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
2c4b0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 f 1. ^When the
2c4c0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 same named.** SQ
2c4d0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 L parameter is u
2c4e0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e sed more than on
2c4f0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 ce, second and s
2c500 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 ubsequent.** occ
2c510 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 urrences have th
2c520 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 e same index as
2c530 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 the first occurr
2c540 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e ence..** ^The in
2c550 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 dex for named pa
2c560 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 rameters can be
2c570 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 looked up using
2c580 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
2c590 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2c5a0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 ndex()] API if d
2c5b0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e esired. ^The in
2c5c0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e dex.** for "?NNN
2c5d0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 " parameters is
2c5e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e the value of NNN
2c5f0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 ..** ^The NNN va
2c600 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 lue must be betw
2c610 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 een 1 and the [s
2c620 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a qlite3_limit()].
2c630 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 ** parameter [SQ
2c640 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
2c650 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 BLE_NUMBER] (def
2c660 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 ault value: 999)
2c670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
2c680 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
2c690 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 he value to bind
2c6a0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
2c6b0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 r..** ^If the th
2c6c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
2c6d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2c6e0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f xt() or sqlite3_
2c6f0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a bind_text16().**
2c700 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2c710 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c _blob() is a NUL
2c720 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 L pointer then t
2c730 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2c740 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 ter.** is ignore
2c750 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 d and the end re
2c760 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 sult is the same
2c770 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 as sqlite3_bind
2c780 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e _null()..**.** ^
2c790 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e (In those routin
2c7a0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 es that have a f
2c7b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
2c7c0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 its value is the
2c7d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 .** number of by
2c7e0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d tes in the param
2c7f0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 eter. To be cle
2c800 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 ar: the value is
2c810 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2c820 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 f <u>bytes</u> i
2c830 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 n the value, not
2c840 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2c850 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 haracters.)^.**
2c860 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
2c870 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2c880 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
2c890 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2c8a0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e text16().** is n
2c8b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
2c8c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
2c8d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 string is.** the
2c8e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2c8f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
2c900 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2c910 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 ..** If the four
2c920 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2c930 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2c940 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c b() is negative,
2c950 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 then.** the beh
2c960 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2c970 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d ed..** If a non-
2c980 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 negative fourth
2c990 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f parameter is pro
2c9a0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 vided to sqlite3
2c9b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 _bind_text().**
2c9c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2c9d0 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 text16() or sqli
2c9e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2c9f0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 ) then.** that p
2ca00 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 arameter must be
2ca10 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 the byte offset
2ca20 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 .** where the NU
2ca30 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 L terminator wou
2ca40 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e ld occur assumin
2ca50 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 g the string wer
2ca60 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 e NUL.** termina
2ca70 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c ted. If any NUL
2ca80 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 characters occu
2ca90 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 r at byte offset
2caa0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 s less than .**
2cab0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
2cac0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2cad0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c r then the resul
2cae0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 ting string valu
2caf0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 e will.** contai
2cb00 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e n embedded NULs.
2cb10 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 The result of
2cb20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f expressions invo
2cb30 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a lving strings.**
2cb40 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e with embedded N
2cb50 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ULs is undefined
2cb60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 ..**.** ^The fif
2cb70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 th argument to t
2cb80 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 he BLOB and stri
2cb90 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 ng binding inter
2cba0 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 faces.** is a de
2cbb0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
2cbc0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2cbd0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e BLOB or.** strin
2cbe0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 g after SQLite h
2cbf0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
2cc00 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 it. ^The destr
2cc10 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a uctor is called.
2cc20 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ** to dispose of
2cc30 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 the BLOB or str
2cc40 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
2cc50 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 call to bind API
2cc60 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 fails..** ^If t
2cc70 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2cc80 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 t is.** the spec
2cc90 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 ial value [SQLIT
2cca0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 E_STATIC], then
2ccb0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
2ccc0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 hat the.** infor
2ccd0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 mation is in sta
2cce0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 tic, unmanaged s
2ccf0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
2cd00 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 t need to be fre
2cd10 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ed..** ^If the f
2cd20 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
2cd30 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
2cd40 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
2cd50 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d then.** SQLite m
2cd60 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 akes its own pri
2cd70 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
2cd80 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
2cd90 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 y, before.** the
2cda0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2cdb0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2cdc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 s..**.** ^The si
2cdd0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 xth argument to
2cde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2cdf0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e t64() must be on
2ce00 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f e of.** [SQLITE_
2ce10 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
2ce20 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 TF16], [SQLITE_U
2ce30 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c TF16BE], or [SQL
2ce40 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 ITE_UTF16LE].**
2ce50 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 to specify the e
2ce60 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 ncoding of the t
2ce70 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 ext in the third
2ce80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a parameter. If.
2ce90 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 ** the sixth arg
2cea0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
2ceb0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 _bind_text64() i
2cec0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
2ced0 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 .** allowed valu
2cee0 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 es shown above,
2cef0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 or if the text e
2cf00 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
2cf10 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 rent.** from the
2cf20 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 encoding specif
2cf30 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 ied by the sixth
2cf40 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e parameter, then
2cf50 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2cf60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2cf70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2cf80 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
2cf90 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 ) routine binds
2cfa0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 a BLOB of length
2cfb0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 N that.** is fi
2cfc0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 lled with zeroes
2cfd0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 . ^A zeroblob u
2cfe0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 ses a fixed amou
2cff0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 nt of memory.**
2d000 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 (just an integer
2d010 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a to hold its siz
2d020 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
2d030 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
2d040 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
2d050 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
2d060 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 ve as placeholde
2d070 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f rs for BLOBs who
2d080 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 se.** content is
2d090 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 later written u
2d0a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
2d0b0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 _blob_open | inc
2d0c0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f remental BLOB I/
2d0d0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 O] routines..**
2d0e0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 ^A negative valu
2d0f0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c e for the zerobl
2d100 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 ob results in a
2d110 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
2d120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 ..**.** ^If any
2d130 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 of the sqlite3_b
2d140 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2d150 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 are called with
2d160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
2d170 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 ** for the [prep
2d180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d190 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 or with a prepar
2d1a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 ed statement for
2d1b0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 which.** [sqlit
2d1c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 e3_step()] has b
2d1d0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 een called more
2d1e0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 recently than [s
2d1f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
2d200 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c .** then the cal
2d210 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 l will return [S
2d220 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2d230 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 If any sqlite3_b
2d240 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ind_().** routin
2d250 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 e is passed a [p
2d260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d270 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e t] that has been
2d280 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a finalized, the.
2d290 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 ** result is und
2d2a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
2d2b0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
2d2c0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 ** ^Bindings are
2d2d0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 not cleared by
2d2e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 the [sqlite3_res
2d2f0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a et()] routine..*
2d300 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d * ^Unbound param
2d310 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 eters are interp
2d320 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a reted as NULL..*
2d330 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2d340 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 3_bind_* routine
2d350 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
2d360 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
2d370 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 or an.** [error
2d380 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e code] if anythin
2d390 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
2d3a0 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 ^[SQLITE_TOOBIG
2d3b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2d3c0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 ned if the size
2d3d0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 of a string or B
2d3e0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c LOB.** exceeds l
2d3f0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 imits imposed by
2d400 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
2d410 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c ([SQLITE_LIMIT_L
2d420 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 ENGTH]) or.** [S
2d430 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 QLITE_MAX_LENGTH
2d440 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 ]..** ^[SQLITE_R
2d450 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
2d460 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
2d470 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
2d480 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
2d490 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
2d4a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
2d4b0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
2d4c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2d4d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2d4e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
2d4f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2d500 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
2d510 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
2d520 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2d530 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2d540 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2d550 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
2d570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2d580 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2d590 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
2d5a0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2d5b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2d5c0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2d5d0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 blob64(sqlite3_s
2d5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2d5f0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f void*, sqlite3_
2d600 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
2d610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d620 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2d630 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2d640 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2d650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
2d660 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
2d670 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
2d680 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2d690 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
2d6b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2d6c0 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t, int);.SQLITE_
2d6d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2d6e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2d6f0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
2d700 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
2d710 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 lite3_int64);.SQ
2d720 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2d730 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d740 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 te3_bind_null(sq
2d750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2d770 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2d780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2d790 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
2d7a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
2d7b0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 ,int,void(*)(voi
2d7c0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
2d7d0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2d7e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2d7f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
2d800 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2d810 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
2d820 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
2d830 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2d840 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d850 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
2d860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2d870 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a int, const char*
2d880 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
2d890 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
2d8a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
2d8b0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 *)(void*), unsig
2d8c0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e ned char encodin
2d8d0 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 g);.SQLITE_API i
2d8e0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2d8f0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 L sqlite3_bind_v
2d900 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2d910 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
2d920 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2d930 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2d940 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d950 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
2d960 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2d970 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a *, int, int n);.
2d980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2d990 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
2d9b0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2d9c0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
2d9d0 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 3_uint64);../*.*
2d9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2d9f0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
2da00 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ters.** METHOD:
2da10 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2da20 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
2da30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2da40 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
2da50 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 of [SQL paramete
2da60 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 rs].** in a [pre
2da70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2da80 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 . SQL parameter
2da90 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 s are tokens of
2daa0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c the.** form "?",
2dab0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c "?NNN", ":AAA",
2dac0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 "$AAA", or "@AA
2dad0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 A" that serve as
2dae0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
2daf0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 for values that
2db00 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 are [sqlite3_bi
2db10 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d nd_blob | bound]
2db20 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d .** to the param
2db30 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 eters at a later
2db40 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 time..**.** ^(T
2db50 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 his routine actu
2db60 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
2db70 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 index of the la
2db80 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 rgest (rightmost
2db90 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 ).** parameter.
2dba0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 For all forms ex
2dbb0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 cept ?NNN, this
2dbc0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 will correspond
2dbd0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 to the.** number
2dbe0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d of unique param
2dbf0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d eters. If param
2dc00 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e eters of the ?NN
2dc10 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c N form are used,
2dc20 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 .** there may be
2dc30 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 gaps in the lis
2dc40 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 t.)^.**.** See a
2dc50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2dc60 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2dc70 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2dc80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2dc90 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
2dca0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2dcb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2dcc0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2dcd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2dce0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2dcf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2dd00 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2dd10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2dd20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
2dd30 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a ost Parameter.**
2dd40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2dd50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2dd60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2dd70 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
2dd80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2dd90 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
2dda0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
2ddb0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
2ddc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
2dde0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
2ddf0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
2de00 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
2de10 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
2de20 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
2de30 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
2de40 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
2de50 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
2de60 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
2de70 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
2de80 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
2de90 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
2dea0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
2deb0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
2dec0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
2ded0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
2dee0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
2def0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
2df00 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
2df10 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
2df20 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
2df30 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
2df40 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
2df50 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
2df60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2df70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
2df80 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
2df90 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
2dfa0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
2dfb0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
2dfc0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
2dfd0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
2dfe0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
2dff0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
2e000 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
2e010 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
2e020 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
2e030 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
2e040 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
2e050 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
2e060 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
2e070 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
2e080 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
2e090 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
2e0a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2e0b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2e0c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2e0d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2e0e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2e0f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2e100 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
2e110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2e120 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2e130 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2e140 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
2e150 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2e160 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2e170 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2e180 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
2e190 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
2e1a0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
2e1b0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
2e1c0 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 me.** METHOD: sq
2e1d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2e1e0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
2e1f0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
2e200 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
2e210 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
2e220 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
2e230 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
2e240 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
2e250 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
2e260 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2e270 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2e280 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
2e290 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
2e2a0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
2e2b0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
2e2c0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
2e2d0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
2e2e0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
2e2f0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
2e300 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
2e310 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
2e320 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
2e330 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
2e340 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2e350 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2e360 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2e370 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2e380 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2e390 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2e3a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2e3b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2e3c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2e3d0 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f e()]..*/.SQLITE_
2e3e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2e3f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2e400 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2e410 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dex(sqlite3_stmt
2e420 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
2e430 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
2e440 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c PI3REF: Reset Al
2e450 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 l Bindings On A
2e460 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2e470 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 nt.** METHOD: sq
2e480 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2e490 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 ^Contrary to th
2e4a0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d e intuition of m
2e4b0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 any, [sqlite3_re
2e4c0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 set()] does not
2e4d0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 reset.** the [sq
2e4e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2e4f0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 | bindings] on a
2e500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2e510 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 ment]..** ^Use t
2e520 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
2e530 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
2e540 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
2e550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2e560 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2e570 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 LL sqlite3_clear
2e580 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
2e590 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2e5a0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2e5b0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
2e5c0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 A Result Set.**
2e5d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2e5e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
2e5f0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
2e600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2e610 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
2e620 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
2e630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2e640 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e t]. ^This routin
2e650 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 e returns 0 if p
2e660 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a Stmt is an SQL.*
2e670 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 * statement that
2e680 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
2e690 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
2e6a0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
2e6b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2e6c0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
2e6d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 ount()].*/.SQLIT
2e6e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2e6f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2e700 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 _column_count(sq
2e710 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2e720 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e730 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 REF: Column Name
2e740 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
2e750 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2e760 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2e770 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2e780 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
2e790 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
2e7a0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
2e7b0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
2e7c0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
2e7d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e T] statement. ^
2e7e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2e7f0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 mn_name().** int
2e800 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2e810 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
2e820 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2e830 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e F-8 string.** an
2e840 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2e850 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e _name16() return
2e860 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
2e870 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2e880 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
2e890 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 g. ^The first p
2e8a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2e8b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e8c0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
2e8d0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
2e8e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
2e8f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
2e900 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
2e910 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 column number.
2e920 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
2e930 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 lumn is number 0
2e940 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ..**.** ^The ret
2e950 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
2e960 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
2e970 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
2e980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e990 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
2e9a0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
2e9b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
2e9c0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 ntil the stateme
2e9d0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 nt is automatica
2e9e0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 lly.** reprepare
2e9f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 d by the first c
2ea00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2ea10 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 step()] for a pa
2ea20 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 rticular run.**
2ea30 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 or until the nex
2ea40 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c t call to.** sql
2ea50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2ea60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
2ea70 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e lumn_name16() on
2ea80 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
2ea90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ..**.** ^If sqli
2eaa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
2eab0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
2eac0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
2ead0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
2eae0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
2eaf0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
2eb00 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
2eb10 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
2eb20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
2eb30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
2eb40 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
2eb50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
2eb60 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2eb70 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
2eb80 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
2eb90 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
2eba0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
2ebb0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
2ebc0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
2ebd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
2ebe0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
2ebf0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
2ec00 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
2ec10 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
2ec20 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 o the next..*/.S
2ec30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2ec40 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
2ec50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2ec60 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
2ec70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
2ec80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2ec90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
2eca0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2ecb0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
2ecc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
2ecd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ece0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
2ecf0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
2ed00 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 sult.** METHOD:
2ed10 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2ed20 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2ed30 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
2ed40 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
2ed50 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 the database, ta
2ed60 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c ble, and.** tabl
2ed70 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 e column that is
2ed80 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 the origin of a
2ed90 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 particular resu
2eda0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 lt column in.**
2edb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2edc0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 nt..** ^The name
2edd0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2ede0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
2edf0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
2ee00 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
2ee10 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
2ee20 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
2ee30 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 _database_ rout
2ee40 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 ines return.** t
2ee50 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
2ee60 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f , the _table_ ro
2ee70 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2ee80 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e e table name, an
2ee90 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f d.** the origin_
2eea0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2eeb0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 the column name
2eec0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
2eed0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
2eee0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
2eef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ef00 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
2ef10 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
2ef20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2ef30 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2ef40 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2ef50 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2ef60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2ef70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2ef80 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2ef90 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2efa0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
2efb0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
2efc0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
2efd0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
2efe0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
2eff0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
2f000 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
2f010 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
2f020 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
2f030 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
2f040 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
2f050 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2f060 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
2f070 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
2f080 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
2f090 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
2f0a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2f0b0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
2f0c0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
2f0d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
2f0e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
2f0f0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
2f100 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
2f110 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
2f120 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
2f130 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
2f140 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
2f150 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
2f160 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
2f170 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
2f180 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
2f190 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
2f1a0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
2f1b0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
2f1c0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
2f1d0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
2f1e0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
2f1f0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
2f200 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
2f210 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
2f220 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
2f230 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
2f240 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
2f250 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
2f260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
2f270 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2f280 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
2f290 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
2f2a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
2f2b0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
2f2c0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
2f2d0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
2f2e0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
2f2f0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
2f300 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
2f310 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
2f320 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
2f330 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
2f340 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
2f350 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
2f360 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
2f370 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
2f380 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
2f390 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
2f3a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
2f3b0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
2f3c0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
2f3d0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
2f3e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
2f3f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
2f400 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
2f410 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
2f420 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
2f430 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
2f440 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
2f450 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
2f460 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
2f470 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2f480 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
2f490 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
2f4a0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
2f4b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2f4c0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
2f4d0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
2f4e0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
2f4f0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
2f500 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
2f510 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
2f520 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
2f530 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
2f540 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2f550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2f560 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
2f570 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2f580 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
2f590 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
2f5a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2f5b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2f5c0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
2f5d0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f5e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 _database_name16
2f5f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2f600 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2f610 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
2f620 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2f630 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2f640 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2f650 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2f660 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2f670 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2f680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
2f690 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
2f6a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2f6b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2f6c0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
2f6d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2f6e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
2f6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2f700 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2f710 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
2f720 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2f730 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2f740 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2f750 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
2f760 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
2f770 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
2f780 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2f790 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2f7a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
2f7b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
2f7c0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 ter is a [prepar
2f7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
2f7e0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d * If this statem
2f7f0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 ent is a [SELECT
2f800 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 ] statement and
2f810 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
2f820 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 f the.** returne
2f830 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 d result set of
2f840 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 that [SELECT] is
2f850 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 a table column
2f860 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 (not an.** expre
2f870 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
2f880 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c y) then the decl
2f890 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 ared type of the
2f8a0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e table.** column
2f8b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
2f8c0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
2f8d0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
2f8e0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 t set is an.** e
2f8f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
2f900 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 query, then a NU
2f910 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2f920 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 turned..** ^The
2f930 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2f940 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
2f950 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e encoded..**.** ^
2f960 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 (For example, gi
2f970 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 ven the database
2f980 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 schema:.**.** C
2f990 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 REATE TABLE t1(c
2f9a0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 1 VARIANT);.**.*
2f9b0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 * and the follow
2f9c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f ing statement to
2f9d0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a be compiled:.**
2f9e0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 .** SELECT c1 +
2f9f0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 1, c1 FROM t1;.*
2fa00 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e *.** this routin
2fa10 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 e would return t
2fa20 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 he string "VARIA
2fa30 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f NT" for the seco
2fa40 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c nd result.** col
2fa50 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 umn (i==1), and
2fa60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 a NULL pointer f
2fa70 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 or the first res
2fa80 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 ult column (i==0
2fa90 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ).)^.**.** ^SQLi
2faa0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
2fab0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e run-time typing.
2fac0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 ^So just becau
2fad0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
2fae0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
2faf0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
2fb00 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
2fb10 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
2fb20 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
2fb30 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
2fb40 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
2fb50 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
2fb60 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
2fb70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
2fb80 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
2fb90 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 t static. ^Type
2fba0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 .** is associate
2fbb0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 d with individua
2fbc0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 l values, not wi
2fbd0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 th the container
2fbe0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c s.** used to hol
2fbf0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a d those values..
2fc00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2fc10 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2fc20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2fc30 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
2fc40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2fc50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2fc60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
2fc70 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2fc80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
2fc90 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
2fca0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
2fcb0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
2fcc0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
2fcd0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
2fce0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2fcf0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
2fd00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
2fd10 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
2fd20 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
2fd30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2fd40 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
2fd50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2fd60 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
2fd70 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
2fd80 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
2fd90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
2fda0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2fdb0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
2fdc0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
2fdd0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
2fde0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
2fdf0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
2fe00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
2fe10 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
2fe20 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
2fe30 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
2fe40 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
2fe50 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
2fe60 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
2fe70 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
2fe80 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
2fe90 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
2fea0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2feb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2fec0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
2fed0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
2fee0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
2fef0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
2ff00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2ff10 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
2ff20 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
2ff30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
2ff40 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
2ff50 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
2ff60 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
2ff70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2ff80 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
2ff90 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
2ffa0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
2ffb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
2ffc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
2ffd0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
2ffe0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
2fff0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
30000 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
30010 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
30020 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
30030 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
30040 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
30050 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
30060 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
30070 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
30080 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
30090 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
300a0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
300b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
300c0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
300d0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
300e0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
300f0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
30100 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
30110 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
30120 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
30130 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
30140 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
30150 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
30160 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
30170 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
30180 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
30190 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
301a0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
301b0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
301c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a ccurs within an.
301d0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
301e0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
301f0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
30200 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
30210 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
30220 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
30230 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
30240 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
30250 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
30260 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
30270 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
30280 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
30290 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
302a0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
302b0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
302c0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
302d0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
302e0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
302f0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
30300 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
30310 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
30320 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
30330 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
30340 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
30350 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
30360 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
30370 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
30380 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
30390 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
303a0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
303b0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
303c0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
303d0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
303e0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
303f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
30400 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
30410 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
30420 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
30430 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
30440 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
30450 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
30460 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
30470 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
30480 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
30490 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
304a0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
304b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
304c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
304d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
304e0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
304f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
30500 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
30510 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
30520 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
30530 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
30540 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
30550 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
30560 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
30570 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
30580 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
30590 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
305a0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
305b0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
305c0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
305d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
305e0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
305f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
30600 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
30610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
30620 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
30630 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
30640 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
30650 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
30660 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
30670 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
30680 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
30690 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
306a0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
306b0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
306c0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
306d0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
306e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
306f0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
30700 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
30710 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
30720 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
30730 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
30740 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
30750 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
30760 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
30770 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
30780 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
30790 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
307a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
307b0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
307c0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
307d0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
307e0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
307f0 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 *.** For all ver
30800 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
30810 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 up to and includ
30820 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 ing 3.6.23.1, a
30830 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
30840 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 te3_reset()] was
30850 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 required after
30860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 sqlite3_step() r
30870 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 eturned anything
30880 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b .** other than [
30890 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f SQLITE_ROW] befo
308a0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e re any subsequen
308b0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a t invocation of.
308c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
308d0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 ). Failure to r
308e0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
308f0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
30900 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 g .** [sqlite3_r
30910 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 eset()] would re
30920 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 sult in an [SQLI
30930 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 TE_MISUSE] retur
30940 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 n from.** sqlite
30950 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 3_step(). But a
30960 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 fter version 3.6
30970 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 .23.1, sqlite3_s
30980 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
30990 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
309a0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
309b0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
309c0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
309d0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
309e0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
309f0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
30a00 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
30a10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
30a20 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
30a30 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
30a40 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
30a50 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
30a60 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
30a70 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
30a80 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
30a90 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
30aa0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
30ab0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
30ac0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
30ad0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
30ae0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
30af0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
30b00 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
30b10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
30b20 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
30b30 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
30b40 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
30b50 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
30b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
30b70 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
30b80 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
30b90 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
30ba0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
30bb0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
30bc0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
30bd0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
30be0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
30bf0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
30c00 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
30c10 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
30c20 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
30c30 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
30c40 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
30c50 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
30c60 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
30c70 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
30c80 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
30c90 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
30ca0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
30cb0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
30cc0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
30cd0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 ents.** using ei
30ce0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
30cf0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
30d00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
30d10 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v2()] instead.
30d20 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
30d30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30d40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
30d50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
30d60 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
30d70 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
30d80 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
30d90 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
30da0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
30dc0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
30dd0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
30de0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f recommended..*/
30df0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
30e00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
30e10 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
30e20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
30e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
30e40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
30e50 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a n a result set.*
30e60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
30e70 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
30e80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
30e90 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 ount(P) interfac
30ea0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
30eb0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
30ec0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e in the.** curren
30ed0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
30ee0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 ult set of [prep
30ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30f00 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 P..** ^If prepar
30f10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 ed statement P d
30f20 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 oes not have res
30f30 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 ults ready to re
30f40 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c turn.** (via cal
30f50 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ls to the [sqlit
30f60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 e3_column_int |
30f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a sqlite3_column_*
30f80 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ()] of.** interf
30f90 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 aces) then sqlit
30fa0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
30fb0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e returns 0..** ^
30fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
30fd0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e _count(P) routin
30fe0 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 e also returns 0
30ff0 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 if P is a NULL
31000 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 pointer..** ^The
31010 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
31020 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 unt(P) routine r
31030 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 eturns 0 if the
31040 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
31050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
31060 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b p](P) returned [
31070 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e SQLITE_DONE]. ^
31080 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
31090 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c _count(P).** wil
310a0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 l return non-zer
310b0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 o if previous ca
310c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
310d0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 tep](P) returned
310e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d .** [SQLITE_ROW]
310f0 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 , except in the
31100 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 case of the [PRA
31110 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f GMA incremental_
31120 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 vacuum].** where
31130 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
31140 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 ns zero since ea
31150 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 ch step of that
31160 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 multi-step.** pr
31170 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 agma returns 0 c
31180 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a olumns of data..
31190 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
311a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
311b0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 count()].*/.SQLI
311c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
311d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
311e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 3_data_count(sql
311f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
31200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
31210 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 EF: Fundamental
31220 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 Datatypes.** KEY
31230 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 WORDS: SQLITE_TE
31240 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 XT.**.** ^(Every
31250 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 value in SQLite
31260 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 has one of five
31270 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 fundamental dat
31280 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 atypes:.**.** <u
31290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 l>.** <li> 64-bi
312a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
312b0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
312c0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f IEEE floating po
312d0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c int number.** <l
312e0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 i> string.** <li
312f0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e > BLOB.** <li> N
31300 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a ULL.** </ul>)^.*
31310 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
31320 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 ants are codes f
31330 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 or each of those
31340 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f types..**.** No
31350 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 te that the SQLI
31360 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 TE_TEXT constant
31370 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 was also used i
31380 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
31390 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 2.** for a comp
313a0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 letely different
313b0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 meaning. Softw
313c0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 are that links a
313d0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 gainst both.** S
313e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 QLite version 2
313f0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
31400 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 on 3 should use
31410 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f SQLITE3_TEXT, no
31420 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 t.** SQLITE_TEXT
31430 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
31440 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 ITE_INTEGER 1.#
31450 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c define SQLITE_FL
31460 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 OAT 2.#define
31470 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 SQLITE_BLOB
31480 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
31490 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 E_NULL 5.#if
314a0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
314b0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 # undef SQLITE_T
314c0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 EXT.#else.# defi
314d0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 ne SQLITE_TEXT
314e0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 3.#endif.#def
314f0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 ine SQLITE3_TEXT
31500 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 3../*.** CA
31510 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 PI3REF: Result V
31520 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 alues From A Que
31530 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ry.** KEYWORDS:
31540 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 {column access f
31550 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 unctions}.** MET
31560 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
31570 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
31580 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 outines return i
31590 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
315a0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e a single column
315b0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
315c0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 ** result row of
315d0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 a query. ^In e
315e0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
315f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
31600 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
31610 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
31620 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
31630 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
31640 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
31650 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
31660 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
31670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
31680 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
31690 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
316a0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
316b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
316c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
316d0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
316e0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
316f0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
31700 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . ^The leftmost
31710 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
31720 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
31730 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 index 0..** ^Th
31740 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
31750 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
31760 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 t can be determi
31770 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ned using.** [sq
31780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
31790 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 nt()]..**.** If
317a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
317b0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
317c0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
317d0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
317e0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
317f0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
31800 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
31810 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
31820 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
31830 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
31840 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
31850 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
31860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
31870 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
31880 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
31890 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
318a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
318b0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
318c0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
318d0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
318e0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
318f0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
31900 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
31910 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
31920 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
31930 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31940 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
31950 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
31960 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
31970 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
31980 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
31990 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
319a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
319b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
319c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
319d0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
319e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
319f0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
31a00 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
31a10 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
31a20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
31a30 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
31a40 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
31a50 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
31a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
31a70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
31a80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31a90 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
31aa0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
31ab0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
31ac0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
31ad0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
31ae0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 ult column. ^Th
31af0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 e returned value
31b00 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
31b10 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 TE_INTEGER],.**
31b20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 [SQLITE_FLOAT],
31b30 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b [SQLITE_TEXT], [
31b40 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 SQLITE_BLOB], or
31b50 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 [SQLITE_NULL].
31b60 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 The value.** re
31b70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
31b80 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
31b90 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 is only meaningf
31ba0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a ul if no type.**
31bb0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 conversions hav
31bc0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 e occurred as de
31bd0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 scribed below.
31be0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e After a type con
31bf0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 version,.** the
31c00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
31c10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
31c20 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 _type() is undef
31c30 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a ined. Future.**
31c40 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
31c50 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 ite may change t
31c60 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 he behavior of s
31c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
31c80 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e pe().** followin
31c90 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 g a type convers
31ca0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ion..**.** ^If t
31cb0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
31cc0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
31cd0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
31ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
31cf0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
31d00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
31d10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
31d20 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
31d30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
31d40 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
31d50 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
31d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31d70 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
31d80 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
31d90 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
31da0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
31db0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
31dc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
31dd0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
31de0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
31df0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 umn_bytes() uses
31e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
31e10 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
31e20 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
31e30 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 o a UTF-8 string
31e40 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
31e50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
31e60 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
31e70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
31e80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
31e90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
31ea0 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 mn_bytes() retur
31eb0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
31ec0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
31ed0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 a BLOB or UTF-1
31ee0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 6 string then th
31ef0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31f00 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f _bytes16().** ro
31f10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
31f20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
31f30 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
31f40 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
31f50 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
31f60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 UTF-8 string, t
31f70 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
31f80 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e mn_bytes16() con
31f90 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
31fa0 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e ing to UTF-16 an
31fb0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
31fc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
31fd0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
31fe0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
31ff0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
32000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32010 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b es16() uses.** [
32020 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
32030 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
32040 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
32050 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 TF-16 string and
32060 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
32070 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
32080 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
32090 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
320a0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
320b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
320c0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 ytes16() returns
320d0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 zero..**.** ^Th
320e0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
320f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
32100 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
32110 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 d .** [sqlite3_c
32120 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
32130 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 do not include
32140 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
32150 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a tors at the end.
32160 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
32170 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a . ^For clarity:
32180 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 the values retu
32190 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
321a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
321b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
321c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
321d0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 )] are the numbe
321e0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
321f0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
32200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
32210 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
32220 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e ^Strings return
32230 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
32240 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
32250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32260 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
32270 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
32280 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d are always zero-
32290 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
322a0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
322b0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
322c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
322d0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
322e0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f LOB is a NULL po
322f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e inter..**.** <b>
32300 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 Warning:</b> ^Th
32310 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
32320 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
32330 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
32340 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
32350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
32360 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 e] object. In a
32370 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 multithreaded e
32380 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 nvironment,.** a
32390 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
323a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
323b0 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ct may only be u
323c0 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a sed safely with.
323d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
323e0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
323f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
32400 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 lue()]..** If th
32410 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 e [unprotected s
32420 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
32430 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
32440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
32450 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
32460 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 used in any othe
32470 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 r way, including
32480 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 calls.** to rou
32490 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
324a0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d te3_value_int()]
324b0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
324c0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
324d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
324e0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 ytes()], the beh
324f0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 avior is not thr
32500 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 eadsafe..**.** T
32510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 hese routines at
32520 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 tempt to convert
32530 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 the value where
32540 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e appropriate. ^
32550 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
32560 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 if the internal
32570 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
32580 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 s FLOAT and a te
32590 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 xt result.** is
325a0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 requested, [sqli
325b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
325c0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
325d0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ly to perform th
325e0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e.** conversion
325f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
32600 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 ^(The following
32610 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 table details th
32620 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a e conversions.**
32630 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 that are applie
32640 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d:.**.** <blockq
32650 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
32660 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
32670 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c tr><th> Internal
32680 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 <br>Type <th> Re
32690 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 quested<br>Type
326a0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e <th> Conversion
326b0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
326c0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e NULL <td> IN
326d0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 TEGER <td> Res
326e0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e ult is 0.** <tr>
326f0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
32700 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
32710 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a > Result is 0.0.
32720 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
32730 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 L <td> TEXT
32740 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
32750 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
32760 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e r.** <tr><td> N
32770 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c ULL <td> BL
32780 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c OB <td> Resul
32790 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
327a0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ter.** <tr><td>
327b0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 INTEGER <td> F
327c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
327d0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 vert from intege
327e0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 r to float.** <t
327f0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
32800 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
32810 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
32820 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 ing of the integ
32830 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
32840 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 NTEGER <td> B
32850 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
32860 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 as INTEGER->TEX
32870 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 T.** <tr><td> F
32880 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOAT <td> INTE
32890 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
328a0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
328b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
328c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
328d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
328e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
328f0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
32900 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
32910 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 LOB <td> [CAS
32920 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 T] to BLOB.** <t
32930 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
32940 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
32950 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
32960 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
32970 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
32980 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b FLOAT <td> [
32990 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a CAST] to REAL.**
329a0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
329b0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
329c0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
329d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
329e0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
329f0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d ER <td> [CAST]
32a00 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c to INTEGER.** <
32a10 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
32a20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
32a30 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 <td> [CAST] to R
32a40 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EAL.** <tr><td>
32a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
32a60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
32a70 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
32a80 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
32a90 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
32aa0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
32ab0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
32ac0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
32ad0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
32ae0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
32af0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
32b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32b10 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
32b20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
32b30 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
32b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
32b50 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
32b60 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
32b70 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
32b80 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
32b90 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
32ba0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
32bb0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
32bc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
32bd0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
32be0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
32bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32c00 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
32c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32c20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
32c30 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
32c40 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
32c50 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
32c60 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
32c70 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
32c80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
32c90 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
32ca0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
32cb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
32cc0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
32cd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
32ce0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
32cf0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
32d00 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
32d10 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
32d20 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
32d30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
32d40 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
32d50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
32d60 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
32d70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
32d80 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
32d90 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
32da0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
32db0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
32dc0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
32dd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
32de0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
32df0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
32e00 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
32e10 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
32e20 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
32e30 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
32e40 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
32e50 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
32e60 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
32e70 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
32e80 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
32e90 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
32ea0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
32eb0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
32ec0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
32ed0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
32ee0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
32ef0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
32f00 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
32f10 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
32f20 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
32f30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
32f40 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
32f50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
32f60 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 t policy is to i
32f70 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
32f80 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
32f90 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
32fa0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
32fb0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
32fc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
32fd0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
32fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
32ff0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
33000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
33010 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
33020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33030 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
33040 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
33050 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
33060 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
33070 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33080 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
33090 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
330a0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
330b0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
330c0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
330d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
330e0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
330f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
33100 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
33110 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
33120 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
33130 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
33140 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
33150 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
33160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33170 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
33180 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
33190 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
331a0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
331b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
331c0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
331d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
331e0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
331f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
33200 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
33210 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
33220 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
33230 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
33240 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
33250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
33260 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s()..**.** ^The
33270 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
33280 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
33290 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
332a0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
332b0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
332c0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
332d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
332e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
332f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
33300 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
33310 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d alled. ^The mem
33320 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
33330 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
33340 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
33350 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
33360 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c ly. Do <em>not<
33370 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f /em> pass the po
33380 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
33390 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
333a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
333b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
333c0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
333d0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
333e0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
333f0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
33400 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
33410 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
33420 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
33430 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
33440 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
33450 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
33460 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
33470 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
33480 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
33490 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
334a0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
334b0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
334c0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
334d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
334e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
334f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
33500 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
33510 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
33520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
33530 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
33550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
33560 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
33570 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
33580 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33590 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
335a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
335b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
335c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
335d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
335e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
335f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
33600 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
33610 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 double SQLITE_S
33620 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
33630 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
33640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
33650 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
33660 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
33670 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
33680 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f umn_int(sqlite3_
33690 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
336a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
336b0 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 ite3_int64 SQLIT
336c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
336d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 3_column_int64(s
336e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
336f0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
33700 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
33710 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f ed char *SQLITE_
33720 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33730 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
33740 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
33750 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
33760 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
33770 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33790 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
337a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
337b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
337c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
337d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
337e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
337f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
33800 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 PI sqlite3_value
33810 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
33820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33830 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
33840 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
33850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33860 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
33870 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
33880 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 ject.** DESTRUCT
33890 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
338a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
338b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 te3_finalize() f
338c0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
338d0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 d to delete a [p
338e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
338f0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d t]..** ^If the m
33900 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
33910 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 ation of the sta
33920 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 tement encounter
33930 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 ed no errors.**
33940 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d or if the statem
33950 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 ent is never bee
33960 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 n evaluated, the
33970 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 n sqlite3_finali
33980 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 ze() returns.**
33990 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 SQLITE_OK. ^If
339a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
339b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 evaluation of st
339c0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 atement S failed
339d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
339e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 3_finalize(S) re
339f0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 turns the approp
33a00 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
33a10 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
33a20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a ed error code]..
33a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
33a40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
33a50 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 outine can be ca
33a60 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e lled at any poin
33a70 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 t during.** the
33a80 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 life cycle of [p
33a90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33aa0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 t] S:.** before
33ab0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 statement S is e
33ac0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 ver evaluated, a
33ad0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d fter.** one or m
33ae0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ore calls to [sq
33af0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 lite3_reset()],
33b00 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c or after any cal
33b10 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 l.** to [sqlite3
33b20 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c _step()] regardl
33b30 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
33b40 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d r not the statem
33b50 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c ent has.** compl
33b60 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a eted execution..
33b70 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 **.** ^Invoking
33b80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33b90 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 () on a NULL poi
33ba0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 nter is a harmle
33bb0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 ss no-op..**.**
33bc0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
33bd0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 must finalize ev
33be0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 ery [prepared st
33bf0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 atement] in orde
33c00 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 r to avoid.** re
33c10 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 source leaks. I
33c20 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 t is a grievous
33c30 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 error for the ap
33c40 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 plication to try
33c50 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 to use.** a pre
33c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
33c70 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
33c80 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e n finalized. An
33c90 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 y use of a prepa
33ca0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
33cb0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
33cc0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e en finalized can
33cd0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
33ce0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 ined and.** unde
33cf0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
33d00 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c such as segfaul
33d10 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 ts and heap corr
33d20 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 uption..*/.SQLIT
33d30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33d40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
33d50 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
33d60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
33d70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33d80 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
33d90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
33da0 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ct.** METHOD: sq
33db0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
33dc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
33dd0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
33de0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
33df0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
33e00 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
33e10 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
33e20 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
33e30 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
33e40 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 uted..** ^Any SQ
33e50 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 L statement vari
33e60 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 ables that had v
33e70 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 alues bound to t
33e80 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hem using.** the
33e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
33ea0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
33eb0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 nd_*() API] reta
33ec0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
33ed0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 .** Use [sqlite3
33ee0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
33ef0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
33f00 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 bindings..**.**
33f10 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
33f20 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
33f30 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
33f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
33f50 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 ] S.** back to t
33f60 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
33f70 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
33f80 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
33f90 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
33fa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
33fb0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
33fc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
33fd0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
33fe0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
33ff0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 ITE_DONE],.** or
34000 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
34010 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
34020 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
34030 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e ed on S,.** then
34040 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34050 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
34060 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
34070 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
34080 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
34090 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
340a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
340b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
340c0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
340d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 r, then.** [sqli
340e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
340f0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
34100 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
34110 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ]..**.** ^The [s
34120 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
34130 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
34140 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
34150 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 alues.** of any
34160 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
34170 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
34180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
34190 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 atement] S..*/.S
341a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
341b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
341c0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 ite3_reset(sqlit
341d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
341e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
341f0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 : Create Or Rede
34200 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f fine SQL Functio
34210 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ns.** KEYWORDS:
34220 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 {function creati
34230 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 on routines}.**
34240 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
34250 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
34260 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 QL function}.**
34270 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
34280 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
34290 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a QL functions}.**
342a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
342b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
342c0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 nctions (collect
342d0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 ively known as "
342e0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
342f0 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 n routines").**
34300 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
34310 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
34320 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 aggregates or t
34330 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 o redefine the b
34340 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 ehavior.** of ex
34350 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
34360 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
34370 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 es. The only di
34380 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 fferences betwee
34390 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 n.** these routi
343a0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 nes are the text
343b0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 encoding expect
343c0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 ed for.** the se
343d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 cond parameter (
343e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
343f0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 function being c
34400 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 reated).** and t
34410 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 he presence or a
34420 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 bsence of a dest
34430 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
34440 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 for.** the appli
34450 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
34460 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
34470 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
34480 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 is the [database
34490 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
344a0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a which the SQL.**
344b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 function is to
344c0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 be added. ^If a
344d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
344e0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 es more than one
344f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
34500 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 nection then app
34510 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34520 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d SQL functions m
34530 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 ust be added.**
34540 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
34550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 connection sepa
34560 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rately..**.** ^T
34570 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
34580 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
34590 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
345a0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
345b0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
345c0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 d. ^The length
345d0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
345e0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
345f0 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a tes in a UTF-8.*
34600 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e * representation
34610 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 , exclusive of t
34620 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
34630 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 or. ^Note that
34640 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 the name.** leng
34650 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 th limit is in U
34660 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 TF-8 bytes, not
34670 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 characters nor U
34680 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a TF-16 bytes. .*
34690 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 * ^Any attempt t
346a0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 o create a funct
346b0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 ion with a longe
346c0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 r name.** will r
346d0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 esult in [SQLITE
346e0 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 _MISUSE] being r
346f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
34700 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
34710 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 ter (nArg).** is
34720 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
34730 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
34740 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
34750 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
34760 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 akes. ^If this p
34770 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 arameter is -1,
34780 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
34790 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
347a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
347b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
347c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 uments between 0
347d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a and the limit.*
347e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 * set by [sqlite
347f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
34800 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
34810 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 ARG]). If the t
34820 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
34830 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d r is less than -
34840 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
34850 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 n 127 then the b
34860 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
34870 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
34880 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
34890 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
348a0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
348b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
348c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
348d0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
348e0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
348f0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
34900 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
34910 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 n should set thi
34920 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a s parameter to.*
34930 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
34940 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 E] if the functi
34950 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
34960 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 n invokes .** [s
34970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34980 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 t16le()] on an i
34990 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 nput, or [SQLITE
349a0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 _UTF16BE] if the
349b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
349c0 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 on invokes [sqli
349d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
349e0 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 be()] on an inpu
349f0 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 t, or.** [SQLITE
34a00 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 _UTF16] if [sqli
34a10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34a20 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 ()] is used, or
34a30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a [SQLITE_UTF8].**
34a40 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 otherwise. ^Th
34a50 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
34a60 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
34a70 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 tered multiple t
34a80 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 imes using.** di
34a90 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 fferent preferre
34aa0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
34ab0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 , with different
34ac0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
34ad0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 for.** each enc
34ae0 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 oding..** ^When
34af0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
34b00 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
34b10 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 same function ar
34b20 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c e available, SQL
34b30 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b ite.** will pick
34b40 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e the one that in
34b50 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 volves the least
34b60 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
34b70 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
34b80 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
34b90 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 rameter may opti
34ba0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 onally be ORed w
34bb0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 ith [SQLITE_DETE
34bc0 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f RMINISTIC].** to
34bd0 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 signal that the
34be0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 function will a
34bf0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 lways return the
34c00 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 same result giv
34c10 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 en.** the same i
34c20 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 nputs within a s
34c30 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
34c40 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 ent. Most SQL f
34c50 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 unctions are.**
34c60 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 deterministic.
34c70 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 The built-in [ra
34c80 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 ndom()] SQL func
34c90 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 tion is an examp
34ca0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 le of a.** funct
34cb0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 ion that is not
34cc0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 deterministic.
34cd0 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 The SQLite query
34ce0 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 planner is able
34cf0 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 to.** perform a
34d00 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 dditional optimi
34d10 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 zations on deter
34d20 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f ministic functio
34d30 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 ns, so use.** of
34d40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 the [SQLITE_DET
34d50 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 ERMINISTIC] flag
34d60 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
34d70 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a where possible..
34d80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 **.** ^(The fift
34d90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
34da0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e n arbitrary poin
34db0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ter. The implem
34dc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a entation of the.
34dd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ** function can
34de0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 gain access to t
34df0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e his pointer usin
34e00 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f g [sqlite3_user_
34e10 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a data()].)^.**.**
34e20 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 ^The sixth, sev
34e30 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 enth and eighth
34e40 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
34e50 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
34e60 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
34e70 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
34e80 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
34e90 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
34ea0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
34eb0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 ** aggregate. ^A
34ec0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
34ed0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
34ee0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34ef0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 of the xFunc.**
34f00 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e callback only; N
34f10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 ULL pointers mus
34f20 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 t be passed as t
34f30 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 he xStep and xFi
34f40 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 nal.** parameter
34f50 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 s. ^An aggregate
34f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
34f70 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
34f80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
34f90 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
34fa0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 and NULL pointer
34fb0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
34fc0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 for xFunc. ^To d
34fd0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e elete an existin
34fe0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f g.** SQL functio
34ff0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
35000 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 pass NULL pointe
35010 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 rs for all three
35020 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c function.** cal
35030 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 lbacks..**.** ^(
35040 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 If the ninth par
35050 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
35060 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35070 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 n_v2() is not NU
35080 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 LL,.** then it i
35090 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 s destructor for
350a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
350b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a data pointer. .
350c0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f ** The destructo
350d0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 r is invoked whe
350e0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 n the function i
350f0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 s deleted, eithe
35100 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 r by being.** ov
35110 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e erloaded or when
35120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
35130 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e nnection closes.
35140 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 )^.** ^The destr
35150 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e uctor is also in
35160 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c voked if the cal
35170 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
35180 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
35190 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e v2() fails..** ^
351a0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 When the destruc
351b0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 tor callback of
351c0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 the tenth parame
351d0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ter is invoked,
351e0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 it.** is passed
351f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
35200 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 t which is a cop
35210 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 y of the applica
35220 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f tion data .** po
35230 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 inter which was
35240 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 the fifth parame
35250 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
35260 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
35270 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 2()..**.** ^It i
35280 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 s permitted to r
35290 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 egister multiple
352a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
352b0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
352c0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 functions with t
352d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
352e0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 with either dif
352f0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f fering numbers o
35300 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f f.** arguments o
35310 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 r differing pref
35320 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
35330 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 ings. ^SQLite w
35340 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 ill use.** the i
35350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 mplementation th
35360 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 at most closely
35370 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 matches the way
35380 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 in which the.**
35390 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
353a0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 used. ^A functi
353b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
353c0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 n with a non-neg
353d0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 ative.** nArg pa
353e0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 rameter is a bet
353f0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ter match than a
35400 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
35410 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a entation with.**
35420 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 a negative nArg
35430 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 . ^A function w
35440 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
35450 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
35460 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
35470 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
35480 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
35490 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
354a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
354b0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
354c0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 ferent. .** ^A
354d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
354e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
354f0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 erence is betwee
35500 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 n UTF16le and UT
35510 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c F16be.** is a cl
35520 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 oser match than
35530 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
35540 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
35550 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 fference is.** b
35560 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 etween UTF8 and
35570 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 UTF16..**.** ^Bu
35580 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
35590 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 may be overload
355a0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 ed by new applic
355b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
355c0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e nctions..**.** ^
355d0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 An application-d
355e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
355f0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
35600 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 call other.** SQ
35610 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e Lite interfaces.
35620 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 However, such
35630 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a calls must not.*
35640 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 * close the data
35650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
35660 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 nor finalize or
35670 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
35680 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
35690 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e in which the fun
356a0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
356b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
356c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
356d0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 LL sqlite3_creat
356e0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
356f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
35700 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
35710 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
35720 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
35730 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
35740 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
35750 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
35760 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
35770 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
35780 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
35790 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
357a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
357b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
357c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
357d0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
357e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
357f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 ALL sqlite3_crea
35800 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
35810 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
35820 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
35830 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
35840 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
35850 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
35860 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
35870 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
35880 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
35890 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
358a0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
358b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
358c0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
358d0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
358e0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
358f0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
35900 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
35910 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
35920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
35930 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
35940 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
35950 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
35960 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
35970 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
35980 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
35990 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
359a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
359b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
359c0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
359d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
359e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
359f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
35a00 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
35a10 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 context*),. voi
35a20 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
35a30 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
35a40 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
35a50 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
35a60 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
35a70 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
35a80 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
35a90 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
35aa0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
35ab0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
35ac0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
35ad0 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
35ae0 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 1 /* IMP:
35af0 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a R-37514-35566 *
35b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
35b10 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 _UTF16LE
35b20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 2 /* IMP: R-0
35b30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 3371-37637 */.#d
35b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
35b50 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 16BE 3
35b60 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 /* IMP: R-51971
35b70 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e -34154 */.#defin
35b80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 e SQLITE_UTF16
35b90 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 4 /*
35ba0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 Use native byte
35bb0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 order */.#define
35bc0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 SQLITE_ANY
35bd0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 5 /* D
35be0 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 eprecated */.#de
35bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
35c00 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 6_ALIGNED 8
35c10 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
35c20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 e_collation only
35c30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
35c40 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c REF: Function Fl
35c50 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ags.**.** These
35c60 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 constants may be
35c70 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 ORed together w
35c80 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
35c90 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 ITE_UTF8 | prefe
35ca0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
35cb0 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 ng] as the fourt
35cc0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f h argument.** to
35cd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
35ce0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 _function()], [s
35cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35d00 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a nction16()], or.
35d10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
35d20 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
35d30 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
35d40 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
35d50 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a IC 0x800../*.
35d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 ** CAPI3REF: Dep
35d70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e recated Function
35d80 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a s.** DEPRECATED.
35d90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
35da0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 tions are [depre
35db0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 cated]. In orde
35dc0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a r to maintain.**
35dd0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
35de0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c tibility with ol
35df0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 der code, these
35e00 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e functions contin
35e10 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 ue .** to be sup
35e20 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 ported. However
35e30 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f , new applicatio
35e40 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a ns should avoid.
35e50 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 ** the use of th
35e60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
35e70 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f To encourage pro
35e80 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 grammers to avoi
35e90 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 d.** these funct
35ea0 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f ions, we will no
35eb0 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 t explain what t
35ec0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
35ed0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
35ee0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
35ef0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
35f00 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 ECATED int SQLIT
35f10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
35f20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
35f30 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
35f40 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
35f50 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
35f60 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
35f70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 CALL sqlite3_exp
35f80 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
35f90 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
35fa0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
35fb0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
35fc0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 CALL sqlite3_tra
35fd0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
35fe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
35ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
36000 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
36010 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
36020 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36030 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 lite3_global_rec
36040 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 over(void);.SQLI
36050 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
36060 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 PRECATED void SQ
36070 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
36080 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
36090 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nup(void);.SQLIT
360a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
360b0 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 RECATED int SQLI
360c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
360d0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
360e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
360f0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
36100 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
36110 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 void*,sq
36120 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
36130 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
36140 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
36150 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 SQL Values.** ME
36160 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 THOD: sqlite3_va
36170 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d lue.**.** The C-
36180 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 language impleme
36190 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 ntation of SQL f
361a0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
361b0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 regates uses.**
361c0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 this set of inte
361d0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 rface routines t
361e0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 o access the par
361f0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e ameter values on
36200 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e .** the function
36210 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 or aggregate.
36220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 .**.** The xFunc
36230 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e (for scalar fun
36240 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 ctions) or xStep
36250 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 (for aggregates
36260 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 ) parameters.**
36270 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
36280 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
36290 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
362a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
362b0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 .** define callb
362c0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d acks that implem
362d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
362e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
362f0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 ates..** The 3rd
36300 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
36310 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 ese callbacks is
36320 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
36330 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f nters to.** [pro
36340 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
36350 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
36360 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
36370 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36380 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
36390 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
363a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
363b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
363c0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
363d0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
363e0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
363f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
36400 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
36410 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 nes work only wi
36420 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 th [protected sq
36430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36440 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 ects..** Any att
36450 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 empt to use thes
36460 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e e routines on an
36470 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
36480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
36490 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 object results i
364a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
364b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 vior..**.** ^The
364c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
364d0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
364e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
364f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
36500 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
36510 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 that these rout
36520 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
36530 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
36540 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36550 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
36560 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
36570 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
36580 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
36590 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
365a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
365b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
365c0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
365d0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
365e0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
365f0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
36600 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
36610 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
36620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
36630 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
36640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
36650 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
36660 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
36670 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
36680 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
36690 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
366a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
366b0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
366c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
366d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
366e0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
366f0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
36700 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
36710 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
36720 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
36730 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
36740 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
36750 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
36760 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
36770 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
36780 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
36790 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
367a0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
367b0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
367c0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
367d0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
367e0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
367f0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
36800 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
36810 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
36820 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
36830 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
36840 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
36850 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
36860 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
36870 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
36880 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
36890 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
368a0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
368b0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
368c0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
368d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
368e0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
368f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
36900 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
36910 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
36920 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
36930 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
36940 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
36950 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
36960 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
36970 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
36980 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
36990 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
369a0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
369b0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
369c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
369d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
369e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
369f0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
36a00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
36a10 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
36a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
36a30 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 arameters..*/.SQ
36a40 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
36a50 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
36a60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
36a70 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 e_blob(sqlite3_v
36a80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36a90 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
36aa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
36ab0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 lue_bytes(sqlite
36ac0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
36ad0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
36ae0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
36af0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 _value_bytes16(s
36b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
36b10 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c SQLITE_API doubl
36b20 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c e SQLITE_STDCALL
36b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
36b40 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
36b50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36b60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
36b70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
36b80 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
36b90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36ba0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
36bb0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
36bd0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64(sqlite3_valu
36be0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
36bf0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
36c00 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
36c10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
36c20 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
36c30 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36c40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
36c50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36c60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
36c70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
36c80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
36c90 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
36ca0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
36cb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
36cc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36cd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
36ce0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
36cf0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36d00 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 value_text16be(s
36d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
36d20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
36d30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36d40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
36d50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36d60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
36d70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
36d90 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
36da0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
36db0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e ** CAPI3REF: Fin
36dc0 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 ding The Subtype
36dd0 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a Of SQL Values.*
36de0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
36df0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 3_value.**.** Th
36e00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
36e10 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 subtype(V) funct
36e20 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
36e30 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 subtype for.** a
36e40 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 n [application-d
36e50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
36e60 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e ion] argument V.
36e70 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a The subtype.**
36e80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e information can
36e90 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 be used to pass
36ea0 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e a limited amoun
36eb0 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f t of context fro
36ec0 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e m.** one SQL fun
36ed0 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 ction to another
36ee0 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 . Use the [sqli
36ef0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 te3_result_subty
36f00 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 pe()].** routine
36f10 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 to set the subt
36f20 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 ype for the retu
36f30 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 rn value of an S
36f40 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a QL function..**.
36f50 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
36f60 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 no use of subtyp
36f70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 e itself. It me
36f80 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 rely passes the
36f90 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 subtype.** from
36fa0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e the result of on
36fb0 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 e [application-d
36fc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
36fd0 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ion] into the.**
36fe0 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 input of anothe
36ff0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
37000 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 53 51 unsigned int SQ
37010 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
37020 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 ite3_value_subty
37030 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
37040 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
37050 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 REF: Copy And Fr
37060 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a ee SQL Values.**
37070 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
37080 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 _value.**.** ^Th
37090 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
370a0 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 dup(V) interface
370b0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
370c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
370d0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 lue].** object D
370e0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
370f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 ointer to that c
37100 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 opy. ^The [sqli
37110 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 te3_value] retur
37120 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f ned.** is a [pro
37130 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
37140 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 alue] object eve
37150 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 n if the input i
37160 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 s not..** ^The s
37170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
37180 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (V) interface re
37190 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 turns NULL if V
371a0 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a is NULL or if a.
371b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
371c0 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a tion fails..**.*
371d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
371e0 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 alue_free(V) int
371f0 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 erface frees an
37200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
37210 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f object.** previo
37220 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
37230 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
37240 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 e_dup()]. ^If V
37250 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
37260 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 er.** then sqlit
37270 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 e3_value_free(V)
37280 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
37290 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f o-op..*/.SQLITE_
372a0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
372b0 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f IMENTAL sqlite3_
372c0 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 value *SQLITE_ST
372d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
372e0 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 lue_dup(const sq
372f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
37300 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
37310 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
37320 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
37330 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
37340 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c free(sqlite3_val
37350 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
37360 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
37370 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
37380 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 Context.** METH
37390 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 OD: sqlite3_cont
373a0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d ext.**.** Implem
373b0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 entations of agg
373c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
373d0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a ions use this.**
373e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f routine to allo
373f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 cate memory for
37400 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
37410 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ate..**.** ^The
37420 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 first time the s
37430 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
37440 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f _context(C,N) ro
37450 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
37460 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 .** for a partic
37470 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 ular aggregate f
37480 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a unction, SQLite.
37490 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f ** allocates N o
374a0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 f memory, zeroes
374b0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 out that memory
374c0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 , and returns a
374d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
374e0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f e new memory. ^O
374f0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 n second and sub
37500 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
37510 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
37520 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
37530 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 for the same agg
37540 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
37550 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 instance,.** the
37560 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 same buffer is
37570 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 returned. Sqlit
37580 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
37590 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c text() is normal
375a0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 ly.** called onc
375b0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 e for each invoc
375c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 ation of the xSt
375d0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 ep callback and
375e0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 then one.** last
375f0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 time when the x
37600 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 Final callback i
37610 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 s invoked. ^(Wh
37620 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 en no rows match
37630 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 .** an aggregate
37640 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 query, the xSte
37650 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 p() callback of
37660 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 the aggregate fu
37670 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d nction.** implem
37680 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 entation is neve
37690 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 r called and xFi
376a0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 nal() is called
376b0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a exactly once..**
376c0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c In those cases,
376d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
376e0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 te_context() mig
376f0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 ht be called for
37700 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 the.** first ti
37710 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 me from within x
37720 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a Final().)^.**.**
37730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 ^The sqlite3_ag
37740 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
37750 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 C,N) routine ret
37760 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
37770 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 ter .** when fir
37780 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 st called if N i
37790 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 s less than or e
377a0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 qual to zero or
377b0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 if a memory.** a
377c0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 llocate error oc
377d0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 curs..**.** ^(Th
377e0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 e amount of spac
377f0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 e allocated by s
37800 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
37810 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 _context(C,N) is
37820 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 .** determined b
37830 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 y the N paramete
37840 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 r on first succe
37850 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 ssful call. Cha
37860 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c nging the.** val
37870 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 ue of N in subse
37880 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
37890 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
378a0 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e context() within
378b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 .** the same agg
378c0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
378d0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f instance will no
378e0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d t resize the mem
378f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
37900 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 n.)^ Within the
37910 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
37920 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 , it is customar
37930 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 y to set.** N=0
37940 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 in calls to sqli
37950 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
37960 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 ntext(C,N) so th
37970 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c at no .** pointl
37980 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ess memory alloc
37990 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a ations occur..**
379a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f .** ^SQLite auto
379b0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
379c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
379d0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 ated by .** sqli
379e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
379f0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 ntext() when the
37a00 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
37a10 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
37a20 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
37a30 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 meter must be a
37a40 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
37a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
37a60 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
37a70 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
37a80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
37a90 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 ter.** to the xS
37aa0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 tep or xFinal ca
37ab0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
37ac0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
37ad0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
37ae0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
37af0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
37b00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
37b10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
37b20 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
37b30 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
37b40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
37b50 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
37b60 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 I void *SQLITE_S
37b70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 TDCALL sqlite3_a
37b80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
37b90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37ba0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
37bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37bc0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
37bd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 unctions.** METH
37be0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 OD: sqlite3_cont
37bf0 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ext.**.** ^The s
37c00 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
37c10 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
37c20 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
37c30 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 * the pointer th
37c40 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 at was the pUser
37c50 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 Data parameter (
37c60 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
37c70 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
37c80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
37c90 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
37ca0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
37cb0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
37cc0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
37cd0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
37ce0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
37cf0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
37d00 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
37d10 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
37d20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
37d30 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
37d40 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
37d50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37d60 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
37d70 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
37d80 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
37d90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
37da0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
37db0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
37dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37dd0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
37de0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
37df0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
37e00 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a ite3_context.**.
37e10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37e20 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
37e30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 e() interface re
37e40 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
37e50 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
37e60 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
37e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 connection] (the
37e80 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 1st parameter).
37e90 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
37ea0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
37eb0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 on()].** and [sq
37ec0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
37ed0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 ction16()] routi
37ee0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 nes that origina
37ef0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 lly.** registere
37f00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
37f10 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n defined functi
37f20 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 on..*/.SQLITE_AP
37f30 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 I sqlite3 *SQLIT
37f40 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
37f50 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
37f60 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
37f70 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
37f80 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
37f90 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a Auxiliary Data.
37fa0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
37fb0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
37fc0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
37fd0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 may be used by
37fe0 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 (non-aggregate)
37ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f SQL functions to
38000 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 .** associate me
38010 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 tadata with argu
38020 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 ment values. If
38030 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 the same value i
38040 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d s passed to.** m
38050 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 ultiple invocati
38060 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
38070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 SQL function dur
38080 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 ing query execut
38090 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f ion, under.** so
380a0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 me circumstances
380b0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
380c0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 metadata may be
380d0 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 preserved. An e
380e0 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 xample.** of whe
380f0 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 re this might be
38100 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 useful is in a
38110 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
38120 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 on matching.** f
38130 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d unction. The com
38140 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 piled version of
38150 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
38160 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 ression can be s
38170 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 tored as.** meta
38180 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 data associated
38190 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e with the pattern
381a0 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 string. .** Th
381b0 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 en as long as th
381c0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 e pattern string
381d0 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d remains the sam
381e0 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c e,.** the compil
381f0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 ed regular expre
38200 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 ssion can be reu
38210 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a sed on multiple.
38220 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
38230 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
38240 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
38250 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
38260 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
38270 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
38280 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
38290 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
382a0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
382b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
382c0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
382d0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
382e0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
382f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
38300 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 function. ^If th
38310 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 ere is no metada
38320 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
38330 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 with the functi
38340 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 on argument, thi
38350 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 s sqlite3_get_au
38360 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
38370 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e e.** returns a N
38380 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
38390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
383a0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
383b0 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 P,X) interface s
383c0 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 aves P as metada
383d0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a ta for the N-th.
383e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 ** argument of t
383f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
38400 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
38410 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a ^Subsequent.**
38420 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
38430 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_get_auxdata(C,
38440 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d N) return P from
38450 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
38460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
38470 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 auxdata(C,N,P,X)
38480 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 call if the met
38490 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 adata is still v
384a0 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 alid or.** NULL
384b0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 if the metadata
384c0 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 has been discard
384d0 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 ed..** ^After ea
384e0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
384f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
38500 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 ,N,P,X) where X
38510 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
38520 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
38530 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ke the destructo
38540 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 r function X wit
38550 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 h parameter P ex
38560 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 actly.** once, w
38570 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 hen the metadata
38580 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a is discarded..*
38590 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 * SQLite is free
385a0 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 to discard the
385b0 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 metadata at any
385c0 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a time, including:
385d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 <ul>.** <li> wh
385e0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
385f0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
38600 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c rameter changes,
38610 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e or.** <li> when
38620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
38630 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
38640 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 inalize()] is ca
38650 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 lled for the.**
38660 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 SQL stateme
38670 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 nt, or.** <li> w
38680 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f hen sqlite3_set_
38690 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 auxdata() is inv
386a0 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 oked again on th
386b0 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 e same parameter
386c0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 , or.** <li> dur
386d0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ing the original
386e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
386f0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e data() call when
38700 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 a memory .**
38710 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 allocation er
38720 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c ror occurs. </ul
38730 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 >)^.**.** Note t
38740 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 he last bullet i
38750 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 n particular. T
38760 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 he destructor X
38770 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 in .** sqlite3_s
38780 65 7