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 37 2e 36 2e 33 2e 20 ersion 3.7.6.3.
00b0: 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c By combining al
00c0: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c l the individual
00d0: 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e C code files in
00e0: 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 to this .** sing
00f0: 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 le large file, t
0100: 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 he entire code c
0110: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 an be compiled a
0120: 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 s a single trans
0130: 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 lation.** unit.
0140: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e This allows man
0150: 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 y compilers to d
0160: 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 o optimizations
0170: 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 that would not b
0180: 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 e.** possible if
0190: 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 the files were
01a0: 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 compiled separat
01b0: 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 ely. Performanc
01c0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a e improvements.*
01d0: 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 * of 5% or more
01e0: 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 are commonly see
01f0: 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 n when SQLite is
0200: 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 compiled as a s
0210: 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 ingle.** transla
0220: 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a tion unit..**.**
0230: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c This file is al
0240: 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f l you need to co
0250: 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 mpile SQLite. T
0260: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 o use SQLite in
0270: 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d other.** program
0280: 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 s, you need this
0290: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 file and the "s
02a0: 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 qlite3.h" header
02b0: 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e file that defin
02c0: 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 es.** the progra
02d0: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 mming interface
02e0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 to the SQLite li
02f0: 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 brary. (If you
0300: 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 do not have .**
0310: 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 the "sqlite3.h"
0320: 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 header file at h
0330: 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 and, you will fi
0340: 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 nd a copy embedd
0350: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
0360: 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 text of this fi
0370: 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 le. Search for
0380: 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 "Begin file sqli
0390: 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 te3.h" to find t
03a0: 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 he start.** of t
03b0: 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 he embedded sqli
03c0: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c te3.h header fil
03d0: 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 e.) Additional c
03e0: 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 ode files may be
03f0: 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f needed.** if yo
0400: 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 u want a wrapper
0410: 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 to interface SQ
0420: 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 Lite with your c
0430: 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d hoice of program
0440: 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 ming.** language
0450: 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 . The code for t
0460: 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d he "sqlite3" com
0470: 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 mand-line shell
0480: 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 is also in a.**
0490: 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 separate file. T
04a0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e his file contain
04b0: 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 s only code for
04c0: 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 the core SQLite
04d0: 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 library..*/.#def
04e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 ine SQLITE_CORE
04f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
0500: 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a _AMALGAMATION 1.
0510: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 #ifndef SQLITE_P
0520: 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 RIVATE.# define
0530: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 SQLITE_PRIVATE s
0540: 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 tatic.#endif.#if
0550: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a ndef SQLITE_API.
0560: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
0570: 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a API.#endif./****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e ********** Begin
0590: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e file sqliteInt.
05a0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a *********/./*.**
05d0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 2001 September
05e0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 15.**.** The aut
05f0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f hor disclaims co
0600: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 pyright to this
0610: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e source code. In
0620: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c place of.** a l
0630: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 egal notice, her
0640: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a e is a blessing:
0650: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f .**.** May yo
0660: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f u do good and no
0670: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 t evil..** Ma
0680: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 y you find forgi
0690: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 veness for yours
06a0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 elf and forgive
06b0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 others..** Ma
06c0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 y you share free
06d0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 ly, never taking
06e0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 more than you g
06f0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a ive..**.********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0740: 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e *.** Internal in
0750: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 terface definiti
0760: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a ons for SQLite..
0770: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 **.*/.#ifndef _S
0780: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 QLITEINT_H_.#def
0790: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 ine _SQLITEINT_H
07a0: 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 _../*.** These #
07b0: 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 defines should e
07c0: 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 nable >2GB file
07d0: 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 support on POSIX
07e0: 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 if the.** under
07f0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
0800: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 system supports
0810: 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c it. If the OS l
0820: 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 acks.** large fi
0830: 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 le support, or i
0840: 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 f the OS is wind
0850: 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c ows, these shoul
0860: 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a d be no-ops..**.
0870: 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a ** Ticket #2739:
0880: 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 The _LARGEFILE
0890: 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 _SOURCE macro mu
08a0: 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 st appear before
08b0: 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 any.** system #
08c0: 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 includes. Hence
08d0: 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 , this block of
08e0: 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 code must be the
08f0: 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 very first.** c
0900: 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 ode in all sourc
0910: 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c e files..**.** L
0920: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 arge file suppor
0930: 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 t can be disable
0940: 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 d using the -DSQ
0950: 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 LITE_DISABLE_LFS
0960: 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 switch.** on th
0970: 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 e compiler comma
0980: 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 nd line. This i
0990: 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 s necessary if y
09a0: 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 ou are compiling
09b0: 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 .** on a recent
09c0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 machine (ex: Red
09d0: 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f Hat 7.2) but yo
09e0: 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 u want your code
09f0: 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 to work.** on a
0a00: 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 n older machine
0a10: 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 (ex: Red Hat 6.0
0a20: 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 ). If you compi
0a30: 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e le on Red Hat 7.
0a40: 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 2.** without thi
0a50: 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 s option, LFS is
0a60: 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 enable. But LF
0a70: 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 S does not exist
0a80: 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a in the kernel.*
0a90: 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 * in Red Hat 6.0
0aa0: 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f , so the code wo
0ab0: 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 n't work. Hence
0ac0: 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 , for maximum bi
0ad0: 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c nary.** portabil
0ae0: 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f ity you should o
0af0: 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 mit LFS..**.** S
0b00: 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 imilar is true f
0b10: 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 or Mac OS X. LF
0b20: 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 S is only suppor
0b30: 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 ted on Mac OS X
0b40: 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 9 and later..*/.
0b50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 #ifndef SQLITE_D
0b60: 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 ISABLE_LFS.# def
0b70: 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 ine _LARGE_FILE
0b80: 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 1.# ifndef
0b90: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 _FILE_OFFSET_BI
0ba0: 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 TS.# define _F
0bb0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 ILE_OFFSET_BITS
0bc0: 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 64.# endif.# def
0bd0: 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 ine _LARGEFILE_S
0be0: 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a OURCE 1.#endif..
0bf0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 /*.** Include th
0c00: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
0c10: 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 header output by
0c20: 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 'configure' if
0c30: 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a we're using the.
0c40: 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 ** autoconf-base
0c50: 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 d build.*/.#ifde
0c60: 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 f _HAVE_SQLITE_C
0c70: 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 ONFIG_H.#include
0c80: 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 "config.h".#end
0c90: 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a if../***********
0ca0: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 *** Include sqli
0cb0: 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 teLimit.h in the
0cc0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 middle of sqlit
0cd0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a eInt.h *********
0ce0: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
0cf0: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 *** Begin file s
0d00: 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a qliteLimit.h ***
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d30: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d **/./*.** 2007 M
0d40: 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ay 7.**.** The a
0d50: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 uthor disclaims
0d60: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 copyright to thi
0d70: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
0d80: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 In place of.** a
0d90: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 legal notice, h
0da0: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e ere is a blessin
0db0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 g:.**.** May
0dc0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 you do good and
0dd0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 not evil..**
0de0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 May you find for
0df0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 giveness for you
0e00: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 rself and forgiv
0e10: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 e others..**
0e20: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 May you share fr
0e30: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 eely, never taki
0e40: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 ng more than you
0e50: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a give..**.******
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 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ea0: 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 ***.** .** This
0eb0: 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 file defines var
0ec0: 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 ious limits of w
0ed0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 hat SQLite can p
0ee0: 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a rocess..*/../*.*
0ef0: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 * The maximum le
0f00: 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f ngth of a TEXT o
0f10: 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e r BLOB in bytes.
0f20: 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 This also.**
0f30: 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 limits the size
0f40: 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 of a row in a ta
0f50: 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a ble or index..**
0f60: 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d .** The hard lim
0f70: 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 it is the abilit
0f80: 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 y of a 32-bit si
0f90: 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
0fa0: 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a to count the siz
0fb0: 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 e: 2^31-1 or 214
0fc0: 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 7483647..*/.#ifn
0fd0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c def SQLITE_MAX_L
0fe0: 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 ENGTH.# define S
0ff0: 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 QLITE_MAX_LENGTH
1000: 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 1000000000.#end
1010: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 if../*.** This i
1020: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 s the maximum nu
1030: 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 mber of.**.**
1040: 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 * Columns in a
1050: 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f table.** * Co
1060: 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 lumns in an inde
1070: 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e x.** * Column
1080: 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 s in a view.**
1090: 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 * Terms in the
10a0: 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 SET clause of a
10b0: 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 n UPDATE stateme
10c0: 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 nt.** * Terms
10d0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
10e0: 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 et of a SELECT s
10f0: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a tatement.** *
1100: 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 Terms in the GR
1110: 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 OUP BY or ORDER
1120: 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 BY clauses of a
1130: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
1140: 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 ..** * Terms
1150: 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c in the VALUES cl
1160: 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 ause of an INSER
1170: 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a T statement.**.*
1180: 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 * The hard upper
1190: 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 limit here is 3
11a0: 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 2676. Most data
11b0: 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c base people will
11c0: 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 .** tell you tha
11d0: 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d t in a well-norm
11e0: 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c alized database,
11f0: 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f you usually sho
1200: 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 uld.** not have
1210: 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 more than a doze
1220: 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 n or so columns
1230: 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 in any table. A
1240: 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 nd if.** that is
1250: 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 the case, there
1260: 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 is no point in
1270: 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e having more than
1280: 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 a few.** dozen
1290: 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 values in any of
12a0: 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 the other situa
12b0: 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 tions described
12c0: 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 above..*/.#ifnde
12d0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c f SQLITE_MAX_COL
12e0: 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c UMN.# define SQL
12f0: 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 ITE_MAX_COLUMN 2
1300: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 000.#endif../*.*
1310: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 * The maximum le
1320: 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 ngth of a single
1330: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
1340: 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 n bytes..**.** I
1350: 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 t used to be the
1360: 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 case that setti
1370: 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f ng this value to
1380: 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 zero would.** t
1390: 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 urn the limit of
13a0: 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c f. That is no l
13b0: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 onger true. It
13c0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a is not possible.
13d0: 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 ** to turn this
13e0: 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 limit off..*/.#i
13f0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1400: 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 _SQL_LENGTH.# de
1410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f fine SQLITE_MAX_
1420: 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 SQL_LENGTH 10000
1430: 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 00000.#endif../*
1440: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 .** The maximum
1450: 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 depth of an expr
1460: 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 ession tree. Thi
1470: 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 s is limited to
1480: 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 .** some extent
1490: 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 by SQLITE_MAX_SQ
14a0: 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f L_LENGTH. But so
14b0: 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 metime you might
14c0: 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 .** want to pla
14d0: 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c ce more severe l
14e0: 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d imits on the com
14f0: 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a plexity of an .*
1500: 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a * expression..**
1510: 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 .** A value of 0
1520: 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 used to mean th
1530: 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 at the limit was
1540: 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a not enforced..*
1550: 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f * But that is no
1560: 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 longer true. T
1570: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 he limit is now
1580: 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 strictly enforce
1590: 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 d.** at all time
15a0: 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 s..*/.#ifndef SQ
15b0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 LITE_MAX_EXPR_DE
15c0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c PTH.# define SQL
15d0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 ITE_MAX_EXPR_DEP
15e0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a TH 1000.#endif..
15f0: 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 /*.** The maximu
1600: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
1610: 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
1620: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
1630: 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 ..** The code ge
1640: 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 nerator for comp
1650: 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
1660: 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a ements does one.
1670: 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 ** level of recu
1680: 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 rsion for each t
1690: 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 erm. A stack ov
16a0: 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c erflow can resul
16b0: 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 t.** if the numb
16c0: 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 er of terms is t
16d0: 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 oo large. In pr
16e0: 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c actice, most SQL
16f0: 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f .** never has mo
1700: 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 re than 3 or 4 t
1710: 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c erms. Use a val
1720: 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 ue of 0 to disab
1730: 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 le.** any limit
1740: 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 on the number of
1750: 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
1760: 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a ount SELECT..*/.
1770: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d #ifndef SQLITE_M
1780: 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 AX_COMPOUND_SELE
1790: 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 CT.# define SQLI
17a0: 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f TE_MAX_COMPOUND_
17b0: 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 SELECT 500.#endi
17c0: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 f../*.** The max
17d0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f imum number of o
17e0: 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 pcodes in a VDBE
17f0: 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 program..** Not
1800: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 currently enfor
1810: 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ced..*/.#ifndef
1820: 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f SQLITE_MAX_VDBE_
1830: 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 OP.# define SQLI
1840: 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 TE_MAX_VDBE_OP 2
1850: 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 5000.#endif../*.
1860: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e ** The maximum n
1870: 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
1880: 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e ts to an SQL fun
1890: 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ction..*/.#ifnde
18a0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e f SQLITE_MAX_FUN
18b0: 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 CTION_ARG.# defi
18c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 ne SQLITE_MAX_FU
18d0: 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 NCTION_ARG 127.#
18e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
18f0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1900: 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 of in-memory pag
1910: 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 es to use for th
1920: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a e main database.
1930: 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 ** table and for
1940: 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 temporary table
1950: 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 s. The SQLITE_D
1960: 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a EFAULT_CACHE_SIZ
1970: 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c E.*/.#ifndef SQL
1980: 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 ITE_DEFAULT_CACH
1990: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 E_SIZE.# define
19a0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 SQLITE_DEFAULT_C
19b0: 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a ACHE_SIZE 2000.
19c0: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
19d0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 QLITE_DEFAULT_TE
19e0: 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 MP_CACHE_SIZE.#
19f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1a00: 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 FAULT_TEMP_CACHE
1a10: 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 _SIZE 500.#endi
1a20: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 f../*.** The def
1a30: 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 ault number of f
1a40: 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c rames to accumul
1a50: 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 ate in the log f
1a60: 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 ile before.** ch
1a70: 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 eckpointing the
1a80: 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 database in WAL
1a90: 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 mode..*/.#ifndef
1aa0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f SQLITE_DEFAULT_
1ab0: 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 WAL_AUTOCHECKPOI
1ac0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 NT.# define SQLI
1ad0: 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 TE_DEFAULT_WAL_A
1ae0: 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 UTOCHECKPOINT 1
1af0: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 000.#endif../*.*
1b00: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 * The maximum nu
1b10: 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 mber of attached
1b20: 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 databases. Thi
1b30: 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 s must be betwee
1b40: 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 n 0.** and 62.
1b50: 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 The upper bound
1b60: 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 on 62 is because
1b70: 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 a 64-bit intege
1b80: 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 r bitmap.** is u
1b90: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
1ba0: 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 o track attached
1bb0: 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 databases..*/.#
1bc0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 ifndef SQLITE_MA
1bd0: 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 X_ATTACHED.# def
1be0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 ine SQLITE_MAX_A
1bf0: 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 TTACHED 10.#endi
1c00: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 f.../*.** The ma
1c10: 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 ximum value of a
1c20: 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 ?nnn wildcard t
1c30: 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 hat the parser w
1c40: 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 ill accept..*/.#
1c50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 ifndef SQLITE_MA
1c60: 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 X_VARIABLE_NUMBE
1c70: 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 R.# define SQLIT
1c80: 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e E_MAX_VARIABLE_N
1c90: 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 UMBER 999.#endif
1ca0: 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 ../* Maximum pag
1cb0: 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 e size. The upp
1cc0: 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 er bound on this
1cd0: 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e value is 65536.
1ce0: 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a This a limit.*
1cf0: 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 * imposed by the
1d00: 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f use of 16-bit o
1d10: 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 ffsets within ea
1d20: 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 ch page..**.** E
1d30: 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 arlier versions
1d40: 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 of SQLite allowe
1d50: 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 d the user to ch
1d60: 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 ange this value
1d70: 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 at.** compile ti
1d80: 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c me. This is no l
1d90: 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c onger permitted,
1da0: 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 on the grounds
1db0: 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a that it creates.
1dc0: 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 ** a library tha
1dd0: 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 t is technically
1de0: 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 incompatible wi
1df0: 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 th an SQLite lib
1e00: 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 rary .** compile
1e10: 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 d with a differe
1e20: 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 nt limit. If a p
1e30: 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 rocess operating
1e40: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a on a database .
1e50: 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 ** with a page-s
1e60: 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 ize of 65536 byt
1e70: 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e es crashes, then
1e80: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
1e90: 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 SQLite .** compi
1ea0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 led with the def
1eb0: 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c ault page-size l
1ec0: 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 imit will not be
1ed0: 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 able to rollbac
1ee0: 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 k .** the aborte
1ef0: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 d transaction. T
1f00: 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 his could lead t
1f10: 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 o database corru
1f20: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 ption..*/.#ifdef
1f30: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
1f40: 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 _SIZE.# undef SQ
1f50: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 LITE_MAX_PAGE_SI
1f60: 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e ZE.#endif.#defin
1f70: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 e SQLITE_MAX_PAG
1f80: 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f E_SIZE 65536.../
1f90: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
1fa0: 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 size of a datab
1fb0: 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 ase page..*/.#if
1fc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 ndef SQLITE_DEFA
1fd0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 ULT_PAGE_SIZE.#
1fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1ff0: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 FAULT_PAGE_SIZE
2000: 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 1024.#endif.#if
2010: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 SQLITE_DEFAULT_P
2020: 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f AGE_SIZE>SQLITE_
2030: 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 MAX_PAGE_SIZE.#
2040: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 undef SQLITE_DEF
2050: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 AULT_PAGE_SIZE.#
2060: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 define SQLITE_D
2070: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 EFAULT_PAGE_SIZE
2080: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
2090: 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a _SIZE.#endif../*
20a0: 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 .** Ordinarily,
20b0: 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 if no value is e
20c0: 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 xplicitly provid
20d0: 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 ed, SQLite creat
20e0: 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 es databases.**
20f0: 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 with page size S
2100: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 QLITE_DEFAULT_PA
2110: 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 GE_SIZE. However
2120: 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 , based on certa
2130: 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 in.** device cha
2140: 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 racteristics (se
2150: 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 ctor-size and at
2160: 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 omic write() sup
2170: 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 port),.** SQLite
2180: 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 may choose a la
2190: 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 rger value. This
21a0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 constant is the
21b0: 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a maximum value.*
21c0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 * SQLite will ch
21d0: 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e oose on its own.
21e0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
21f0: 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 TE_MAX_DEFAULT_P
2200: 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e AGE_SIZE.# defin
2210: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 e SQLITE_MAX_DEF
2220: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 AULT_PAGE_SIZE 8
2230: 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 192.#endif.#if S
2240: 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c QLITE_MAX_DEFAUL
2250: 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 T_PAGE_SIZE>SQLI
2260: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 TE_MAX_PAGE_SIZE
2270: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2280: 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 MAX_DEFAULT_PAGE
2290: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 _SIZE.# define S
22a0: 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c QLITE_MAX_DEFAUL
22b0: 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 T_PAGE_SIZE SQLI
22c0: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 TE_MAX_PAGE_SIZE
22d0: 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 .#endif.../*.**
22e0: 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f Maximum number o
22f0: 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 f pages in one d
2300: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
2310: 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c .** This is real
2320: 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 ly just the defa
2330: 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ult value for th
2340: 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 e max_page_count
2350: 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 pragma..** This
2360: 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f value can be lo
2370: 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 wered (or raised
2380: 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 ) at run-time us
2390: 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ing that the.**
23a0: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d max_page_count m
23b0: 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 acro..*/.#ifndef
23c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
23d0: 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 _COUNT.# define
23e0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
23f0: 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 COUNT 1073741823
2400: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d .#endif../*.** M
2410: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 aximum length (i
2420: 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 n bytes) of the
2430: 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b pattern in a LIK
2440: 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 E or GLOB.** ope
2450: 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 rator..*/.#ifnde
2460: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b f SQLITE_MAX_LIK
2470: 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
2480: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2490: 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 _MAX_LIKE_PATTER
24a0: 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 N_LENGTH 50000.#
24b0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 endif../*.** Max
24c0: 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 imum depth of re
24d0: 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 cursion for trig
24e0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 gers..**.** A va
24f0: 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 lue of 1 means t
2500: 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 hat a trigger pr
2510: 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 ogram will not b
2520: 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 e able to itself
2530: 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 .** fire any tri
2540: 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f ggers. A value o
2550: 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e f 0 means that n
2560: 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 o trigger progra
2570: 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 ms at all .** ma
2580: 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a y be executed..*
2590: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
25a0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 _MAX_TRIGGER_DEP
25b0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 TH.# define SQLI
25c0: 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 TE_MAX_TRIGGER_D
25d0: 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 EPTH 1000.#endif
25e0: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ../*************
25f0: 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c * End of sqliteL
2600: 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a imit.h *********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2630: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
2640: 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 * Continuing whe
2650: 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 re we left off i
2660: 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a n sqliteInt.h **
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2680: 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 /../* Disable nu
2690: 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 isance warnings
26a0: 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 on Borland compi
26b0: 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 lers */.#if defi
26c0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f ned(__BORLANDC__
26d0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d ).#pragma warn -
26e0: 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 rch /* unreachab
26f0: 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 le code */.#prag
2700: 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 ma warn -ccc /*
2710: 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 Condition is alw
2720: 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 ays true or fals
2730: 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 e */.#pragma war
2740: 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e n -aus /* Assign
2750: 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 ed value is neve
2760: 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d r used */.#pragm
2770: 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 a warn -csu /* C
2780: 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 omparing signed
2790: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a and unsigned */.
27a0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 #pragma warn -sp
27b0: 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 a /* Suspicious
27c0: 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 pointer arithmet
27d0: 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a ic */.#endif../*
27e0: 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 Needed for vari
27f0: 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e ous definitions.
2800: 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 .. */.#ifndef _G
2810: 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 NU_SOURCE.# defi
2820: 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 ne _GNU_SOURCE.#
2830: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 endif../*.** Inc
2840: 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 lude standard he
2850: 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 ader files as ne
2860: 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 cessary.*/.#ifde
2870: 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a f HAVE_STDINT_H.
2880: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 #include <stdint
2890: 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 .h>.#endif.#ifde
28a0: 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f f HAVE_INTTYPES_
28b0: 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 H.#include <intt
28c0: 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a ypes.h>.#endif..
28d0: 2f 2a 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 /*.** The number
28e0: 20 6f 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61 of samples of a
28f0: 6e 20 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c n index that SQL
2900: 69 74 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64 ite takes in ord
2910: 65 72 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72 er to .** constr
2920: 75 63 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20 uct a histogram
2930: 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e of the table con
2940: 74 65 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e tent when runnin
2950: 67 20 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64 g ANALYZE.** and
2960: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41 with SQLITE_ENA
2970: 42 4c 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65 BLE_STAT2.*/.#de
2980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
2990: 58 5f 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a X_SAMPLES 10../*
29a0: 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
29b0: 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 g macros are use
29c0: 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 d to cast pointe
29d0: 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 rs to integers a
29e0: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 nd.** integers t
29f0: 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 o pointers. The
2a00: 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 way you do this
2a10: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 varies from one
2a20: 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 compiler.** to
2a30: 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 the next, so we
2a40: 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 have developed t
2a50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 he following set
2a60: 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e of #if statemen
2a70: 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 ts.** to generat
2a80: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 e appropriate ma
2a90: 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 cros for a wide
2aa0: 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 range of compile
2ab0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f rs..**.** The co
2ac0: 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 rrect "ANSI" way
2ad0: 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 to do this is t
2ae0: 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 o use the intptr
2af0: 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 _t type. .** Unf
2b00: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 ortunately, that
2b10: 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 typedef is not
2b20: 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c available on all
2b30: 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a compilers, or.*
2b40: 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c * if it is avail
2b50: 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 able, it require
2b60: 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 s an #include of
2b70: 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72 specific header
2b80: 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 s.** that vary f
2b90: 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 rom one machine
2ba0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a to the next..**.
2bb0: 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a ** Ticket #3860:
2bc0: 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 The llvm-gcc-4
2bd0: 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d .2 compiler from
2be0: 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e Apple chokes on
2bf0: 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 .** the ((void*)
2c00: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 &((char*)0)[X])
2c10: 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 construct. But
2c20: 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 MSVC chokes on (
2c30: 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 (void*)(X))..**
2c40: 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 So we have to de
2c50: 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 fine the macros
2c60: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 in different way
2c70: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 s depending on t
2c80: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a he.** compiler..
2c90: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f */.#if defined(_
2ca0: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 _PTRDIFF_TYPE__)
2cb0: 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 /* This case s
2cc0: 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 hould work for G
2cd0: 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 CC */.# define S
2ce0: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 QLITE_INT_TO_PTR
2cf0: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f (X) ((void*)(__
2d00: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 PTRDIFF_TYPE__)(
2d10: 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c X)).# define SQL
2d20: 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 ITE_PTR_TO_INT(X
2d30: 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 ) ((int)(__PTRD
2d40: 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a IFF_TYPE__)(X)).
2d50: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f #elif !defined(_
2d60: 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f _GNUC__) /
2d70: 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 * Works for comp
2d80: 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e ilers other than
2d90: 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e LLVM */.# defin
2da0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f e SQLITE_INT_TO_
2db0: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 PTR(X) ((void*)
2dc0: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a &((char*)0)[X]).
2dd0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
2de0: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 PTR_TO_INT(X) (
2df0: 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 (int)(((char*)X)
2e00: 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 -(char*)0)).#eli
2e10: 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 f defined(HAVE_S
2e20: 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 TDINT_H) /* Us
2e30: 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77 e this case if w
2e40: 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 e have ANSI head
2e50: 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 ers */.# define
2e60: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 SQLITE_INT_TO_PT
2e70: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 R(X) ((void*)(i
2e80: 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 ntptr_t)(X)).# d
2e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 efine SQLITE_PTR
2ea0: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e _TO_INT(X) ((in
2eb0: 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 t)(intptr_t)(X))
2ec0: 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 .#else
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ee0: 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 /* Generates a w
2ef0: 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 arning - but it
2f00: 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a always works */.
2f10: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
2f20: 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 INT_TO_PTR(X) (
2f30: 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 (void*)(X)).# de
2f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f fine SQLITE_PTR_
2f50: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 TO_INT(X) ((int
2f60: 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a )(X)).#endif../*
2f70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 .** The SQLITE_T
2f80: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 HREADSAFE macro
2f90: 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 must be defined
2fa0: 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a as 0, 1, or 2..*
2fb0: 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 * 0 means mutexe
2fc0: 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c s are permanentl
2fd0: 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 y disable and th
2fe0: 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 e library is nev
2ff0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 er.** threadsafe
3000: 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c . 1 means the l
3010: 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c ibrary is serial
3020: 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68 ized which is th
3030: 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 e highest.** lev
3040: 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 el of threadsafe
3050: 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 ty. 2 means the
3060: 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69 libary is multi
3070: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69 threaded - multi
3080: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63 ple.** threads c
3090: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73 an use SQLite as
30a0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
30b0: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75 threads try to u
30c0: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 se the same.** d
30d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
30e0: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 on at the same t
30f0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72 ime..**.** Older
3100: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
3110: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69 ite used an opti
3120: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20 onal THREADSAFE
3130: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70 macro..** We sup
3140: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65 port that for le
3150: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 gacy..*/.#if !de
3160: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 fined(SQLITE_THR
3170: 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 66 EADSAFE).#if def
3180: 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 29 ined(THREADSAFE)
3190: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
31a0: 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 45 _THREADSAFE THRE
31b0: 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64 ADSAFE.#else.# d
31c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52 efine SQLITE_THR
31d0: 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50 EADSAFE 1 /* IMP
31e0: 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20 : R-07272-22309
31f0: 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 */.#endif.#endif
3200: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ../*.** The SQLI
3210: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 TE_DEFAULT_MEMST
3220: 41 54 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 ATUS macro must
3230: 62 65 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 be defined as ei
3240: 74 68 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 ther 0 or 1..**
3250: 49 74 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 It determines wh
3260: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
3270: 20 66 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 features relate
3280: 64 20 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f d to .** SQLITE_
3290: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
32a0: 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 are available b
32b0: 79 20 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 y default or not
32c0: 2e 20 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e . This value can
32d0: 0a 2a 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 .** be overridde
32e0: 6e 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 n at runtime usi
32f0: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ng the sqlite3_c
3300: 6f 6e 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a onfig() API..*/.
3310: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c #if !defined(SQL
3320: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 ITE_DEFAULT_MEMS
3330: 54 41 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 TATUS).# define
3340: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
3350: 45 4d 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 EMSTATUS 1.#endi
3360: 66 0a 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 f../*.** Exactly
3370: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
3380: 6f 77 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 owing macros mus
3390: 74 20 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 t be defined in
33a0: 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 order to.** spec
33b0: 69 66 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 ify which memory
33c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
33d0: 79 73 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a ystem to use..**
33e0: 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 .** SQLITE_S
33f0: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 YSTEM_MALLOC
3400: 20 20 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 // Use nor
3410: 6d 61 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f mal system mallo
3420: 63 28 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 c().** SQLIT
3430: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20 E_MEMDEBUG
3440: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75 // Debu
3450: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66 gging version of
3460: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
3470: 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f 72 69 63 .**.** (Historic
3480: 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65 72 65 20 al note: There
3490: 75 73 65 64 20 74 6f 20 62 65 20 73 65 76 65 72 used to be sever
34a0: 61 6c 20 6f 74 68 65 72 20 6f 70 74 69 6f 6e 73 al other options
34b0: 2c 20 62 75 74 20 77 65 27 76 65 0a 2a 2a 20 70 , but we've.** p
34c0: 61 72 65 64 20 69 74 20 64 6f 77 6e 20 74 6f 20 ared it down to
34d0: 6a 75 73 74 20 74 68 65 73 65 20 74 77 6f 2e 29 just these two.)
34e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f .**.** If none o
34f0: 66 20 74 68 65 20 61 62 6f 76 65 20 61 72 65 20 f the above are
3500: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 73 65 defined, then se
3510: 74 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f t SQLITE_SYSTEM_
3520: 4d 41 4c 4c 4f 43 20 61 73 0a 2a 2a 20 74 68 65 MALLOC as.** the
3530: 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 23 69 66 default..*/.#if
3540: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f defined(SQLITE_
3550: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 SYSTEM_MALLOC)+d
3560: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 efined(SQLITE_ME
3570: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f MDEBUG)>1.# erro
3580: 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e 65 20 6f r "At most one o
3590: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
35a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e compile-time con
35b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
35c0: 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77 73 3a 20 ns\. is allows:
35d0: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 SQLITE_SYSTEM_MA
35e0: 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 4d 45 4d LLOC, SQLITE_MEM
35f0: 44 45 42 55 47 22 0a 23 65 6e 64 69 66 0a 23 69 DEBUG".#endif.#i
3600: 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 f defined(SQLITE
3610: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b _SYSTEM_MALLOC)+
3620: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d defined(SQLITE_M
3630: 45 4d 44 45 42 55 47 29 3d 3d 30 0a 23 20 64 65 EMDEBUG)==0.# de
3640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 53 54 fine SQLITE_SYST
3650: 45 4d 5f 4d 41 4c 4c 4f 43 20 31 0a 23 65 6e 64 EM_MALLOC 1.#end
3660: 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 53 51 4c if../*.** If SQL
3670: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f ITE_MALLOC_SOFT_
3680: 4c 49 4d 49 54 20 69 73 20 6e 6f 74 20 7a 65 72 LIMIT is not zer
3690: 6f 2c 20 74 68 65 6e 20 74 72 79 20 74 6f 20 6b o, then try to k
36a0: 65 65 70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 73 eep the.** sizes
36b0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 of memory alloc
36c0: 61 74 69 6f 6e 73 20 62 65 6c 6f 77 20 74 68 69 ations below thi
36d0: 73 20 76 61 6c 75 65 20 77 68 65 72 65 20 70 6f s value where po
36e0: 73 73 69 62 6c 65 2e 0a 2a 2f 0a 23 69 66 20 21 ssible..*/.#if !
36f0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d defined(SQLITE_M
3700: 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 ALLOC_SOFT_LIMIT
3710: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 ).# define SQLIT
3720: 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 E_MALLOC_SOFT_LI
3730: 4d 49 54 20 31 30 32 34 0a 23 65 6e 64 69 66 0a MIT 1024.#endif.
3740: 0a 2f 2a 0a 2a 2a 20 57 65 20 6e 65 65 64 20 74 ./*.** We need t
3750: 6f 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f o define _XOPEN_
3760: 53 4f 55 52 43 45 20 61 73 20 66 6f 6c 6c 6f 77 SOURCE as follow
3770: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e s in order to en
3780: 61 62 6c 65 0a 2a 2a 20 72 65 63 75 72 73 69 76 able.** recursiv
3790: 65 20 6d 75 74 65 78 65 73 20 6f 6e 20 6d 6f 73 e mutexes on mos
37a0: 74 20 55 6e 69 78 20 73 79 73 74 65 6d 73 2e 20 t Unix systems.
37b0: 20 42 75 74 20 4d 61 63 20 4f 53 20 58 20 69 73 But Mac OS X is
37c0: 20 64 69 66 66 65 72 65 6e 74 2e 0a 2a 2a 20 54 different..** T
37d0: 68 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 he _XOPEN_SOURCE
37e0: 20 64 65 66 69 6e 65 20 63 61 75 73 65 73 20 70 define causes p
37f0: 72 6f 62 6c 65 6d 73 20 66 6f 72 20 4d 61 63 20 roblems for Mac
3800: 4f 53 20 58 20 77 65 20 61 72 65 20 74 6f 6c 64 OS X we are told
3810: 2c 0a 2a 2a 20 73 6f 20 69 74 20 69 73 20 6f 6d ,.** so it is om
3820: 69 74 74 65 64 20 74 68 65 72 65 2e 20 20 53 65 itted there. Se
3830: 65 20 74 69 63 6b 65 74 20 23 32 36 37 33 2e 0a e ticket #2673..
3840: 2a 2a 0a 2a 2a 20 4c 61 74 65 72 20 77 65 20 6c **.** Later we l
3850: 65 61 72 6e 20 74 68 61 74 20 5f 58 4f 50 45 4e earn that _XOPEN
3860: 5f 53 4f 55 52 43 45 20 69 73 20 70 6f 6f 72 6c _SOURCE is poorl
3870: 79 20 6f 72 20 69 6e 63 6f 72 72 65 63 74 6c 79 y or incorrectly
3880: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 .** implemented
3890: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e on some systems.
38a0: 20 20 53 6f 20 77 65 20 61 76 6f 69 64 20 64 65 So we avoid de
38b0: 66 69 6e 69 6e 67 20 69 74 20 61 74 20 61 6c 6c fining it at all
38c0: 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 6c 72 .** if it is alr
38d0: 65 61 64 79 20 64 65 66 69 6e 65 64 20 6f 72 20 eady defined or
38e0: 69 66 20 69 74 20 69 73 20 75 6e 6e 65 65 64 65 if it is unneede
38f0: 64 20 62 65 63 61 75 73 65 20 77 65 20 61 72 65 d because we are
3900: 0a 2a 2a 20 6e 6f 74 20 64 6f 69 6e 67 20 61 20 .** not doing a
3910: 74 68 72 65 61 64 73 61 66 65 20 62 75 69 6c 64 threadsafe build
3920: 2e 20 20 54 69 63 6b 65 74 20 23 32 36 38 31 2e . Ticket #2681.
3930: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
3940: 74 69 63 6b 65 74 20 23 32 37 34 31 2e 0a 2a 2f ticket #2741..*/
3950: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f 58 .#if !defined(_X
3960: 4f 50 45 4e 5f 53 4f 55 52 43 45 29 20 26 26 20 OPEN_SOURCE) &&
3970: 21 64 65 66 69 6e 65 64 28 5f 5f 44 41 52 57 49 !defined(__DARWI
3980: 4e 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 N__) && !defined
3990: 28 5f 5f 41 50 50 4c 45 5f 5f 29 20 26 26 20 53 (__APPLE__) && S
39a0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
39b0: 0a 23 20 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 .# define _XOPE
39c0: 4e 5f 53 4f 55 52 43 45 20 35 30 30 20 20 2f 2a N_SOURCE 500 /*
39d0: 20 4e 65 65 64 65 64 20 74 6f 20 65 6e 61 62 6c Needed to enabl
39e0: 65 20 70 74 68 72 65 61 64 20 72 65 63 75 72 73 e pthread recurs
39f0: 69 76 65 20 6d 75 74 65 78 65 73 20 2a 2f 0a 23 ive mutexes */.#
3a00: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
3a10: 20 54 43 4c 20 68 65 61 64 65 72 73 20 61 72 65 TCL headers are
3a20: 20 6f 6e 6c 79 20 6e 65 65 64 65 64 20 77 68 65 only needed whe
3a30: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20 n compiling the
3a40: 54 43 4c 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f TCL bindings..*/
3a50: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c .#if defined(SQL
3a60: 49 54 45 5f 54 43 4c 29 20 7c 7c 20 64 65 66 69 ITE_TCL) || defi
3a70: 6e 65 64 28 54 43 4c 53 48 29 0a 23 20 69 6e 63 ned(TCLSH).# inc
3a80: 6c 75 64 65 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e lude <tcl.h>.#en
3a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6e 79 20 dif../*.** Many
3aa0: 70 65 6f 70 6c 65 20 61 72 65 20 66 61 69 6c 69 people are faili
3ab0: 6e 67 20 74 6f 20 73 65 74 20 2d 44 4e 44 45 42 ng to set -DNDEB
3ac0: 55 47 3d 31 20 77 68 65 6e 20 63 6f 6d 70 69 6c UG=1 when compil
3ad0: 69 6e 67 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 53 ing SQLite..** S
3ae0: 65 74 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 etting NDEBUG ma
3af0: 6b 65 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 kes the code sma
3b00: 6c 6c 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 ller and run fas
3b10: 74 65 72 2e 20 20 53 6f 20 74 68 65 20 66 6f 6c ter. So the fol
3b20: 6c 6f 77 69 6e 67 0a 2a 2a 20 6c 69 6e 65 73 20 lowing.** lines
3b30: 61 72 65 20 61 64 64 65 64 20 74 6f 20 61 75 74 are added to aut
3b40: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 74 20 4e omatically set N
3b50: 44 45 42 55 47 20 75 6e 6c 65 73 73 20 74 68 65 DEBUG unless the
3b60: 20 2d 44 53 51 4c 49 54 45 5f 44 45 42 55 47 3d -DSQLITE_DEBUG=
3b70: 31 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 73 1.** option is s
3b80: 65 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 et. Thus NDEBUG
3b90: 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d becomes an opt-
3ba0: 69 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 in rather than a
3bb0: 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 n opt-out.** fea
3bc0: 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 ture..*/.#if !de
3bd0: 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 fined(NDEBUG) &&
3be0: 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 !defined(SQLITE
3bf0: 5f 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e _DEBUG) .# defin
3c00: 65 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 e NDEBUG 1.#endi
3c10: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 65 73 f../*.** The tes
3c20: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 tcase() macro is
3c30: 20 75 73 65 64 20 74 6f 20 61 69 64 20 69 6e 20 used to aid in
3c40: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 coverage testing
3c50: 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f 69 6e . When .** doin
3c60: 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 g coverage testi
3c70: 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74 69 6f ng, the conditio
3c80: 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61 72 67 n inside the arg
3c90: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 73 74 ument to.** test
3ca0: 63 61 73 65 28 29 20 6d 75 73 74 20 62 65 20 65 case() must be e
3cb0: 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20 74 72 valuated both tr
3cc0: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69 6e 20 ue and false in
3cd0: 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65 74 20 order to.** get
3ce0: 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f 76 65 full branch cove
3cf0: 72 61 67 65 2e 20 20 54 68 65 20 74 65 73 74 63 rage. The testc
3d00: 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 20 69 ase() macro is i
3d10: 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20 68 65 nserted.** to he
3d20: 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71 75 61 lp ensure adequa
3d30: 74 65 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 te test coverage
3d40: 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65 72 65 in places where
3d50: 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e 64 69 simple.** condi
3d60: 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f tion/decision co
3d70: 76 65 72 61 67 65 20 69 73 20 69 6e 61 64 65 71 verage is inadeq
3d80: 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 uate. For examp
3d90: 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a le, testcase().*
3da0: 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
3db0: 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75 6e 64 make sure bound
3dc0: 61 72 79 20 76 61 6c 75 65 73 20 61 72 65 20 74 ary values are t
3dd0: 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a 20 62 ested. For.** b
3de0: 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20 74 65 itmask tests, te
3df0: 73 74 63 61 73 65 28 29 20 63 61 6e 20 62 65 20 stcase() can be
3e00: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 used to make sur
3e10: 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20 69 73 e each bit.** is
3e20: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61 6e 64 significant and
3e30: 20 75 73 65 64 20 61 74 20 6c 65 61 73 74 20 6f used at least o
3e40: 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63 68 20 nce. On switch
3e50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 77 68 statements.** wh
3e60: 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63 61 73 ere multiple cas
3e70: 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73 61 6d es go to the sam
3e80: 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 2c e block of code,
3e90: 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63 testcase().** c
3ea0: 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74 20 61 an insure that a
3eb0: 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65 76 61 ll cases are eva
3ec0: 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69 luated..**.*/.#i
3ed0: 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f 56 45 fdef SQLITE_COVE
3ee0: 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49 54 45 RAGE_TEST.SQLITE
3ef0: 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69 64 20 _PRIVATE void
3f00: 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28 sqlite3Coverage(
3f10: 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65 20 74 int);.# define t
3f20: 65 73 74 63 61 73 65 28 58 29 20 20 69 66 28 20 estcase(X) if(
3f30: 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f 76 65 X ){ sqlite3Cove
3f40: 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 3b 20 rage(__LINE__);
3f50: 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 }.#else.# define
3f60: 20 74 65 73 74 63 61 73 65 28 58 29 0a 23 65 6e testcase(X).#en
3f70: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54 dif../*.** The T
3f80: 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 69 73 ESTONLY macro is
3f90: 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f 73 65 used to enclose
3fa0: 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c 61 72 variable declar
3fb0: 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f 74 68 ations or.** oth
3fc0: 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64 65 20 er bits of code
3fd0: 74 68 61 74 20 61 72 65 20 6e 65 65 64 65 64 20 that are needed
3fe0: 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65 20 61 to support the a
3ff0: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 74 68 rguments.** with
4000: 69 6e 20 74 65 73 74 63 61 73 65 28 29 20 61 6e in testcase() an
4010: 64 20 61 73 73 65 72 74 28 29 20 6d 61 63 72 6f d assert() macro
4020: 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e s..*/.#if !defin
4030: 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20 64 65 ed(NDEBUG) || de
4040: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 fined(SQLITE_COV
4050: 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 ERAGE_TEST).# de
4060: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 fine TESTONLY(X)
4070: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 X.#else.# defi
4080: 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 0a 23 ne TESTONLY(X).#
4090: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d endif../*.** Som
40a0: 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64 20 61 etimes we need a
40b0: 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66 small amount of
40c0: 20 63 6f 64 65 20 73 75 63 68 20 61 73 20 61 20 code such as a
40d0: 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69 61 6c variable initial
40e0: 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 73 65 ization.** to se
40f0: 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65 72 20 tup for a later
4100: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 assert() stateme
4110: 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 77 nt. We do not w
4120: 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20 74 6f ant this code to
4130: 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65 6e 20 .** appear when
4140: 61 73 73 65 72 74 28 29 20 69 73 20 64 69 73 61 assert() is disa
4150: 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c 6c 6f bled. The follo
4160: 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20 74 68 wing macro is th
4170: 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65 64 20 erefore.** used
4180: 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61 74 20 to contain that
4190: 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54 68 65 setup code. The
41a0: 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d 20 73 "VVA" acronym s
41b0: 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 56 65 tands for.** "Ve
41c0: 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61 6c 69 rification, Vali
41d0: 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63 63 72 dation, and Accr
41e0: 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49 6e 20 editation". In
41f0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
4200: 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69 6e 20 .** code within
4210: 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c 6c 20 VVA_ONLY() will
4220: 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e 67 20 only run during
4230: 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70 72 6f verification pro
4240: 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 cesses..*/.#ifnd
4250: 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65 66 69 ef NDEBUG.# defi
4260: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 20 20 ne VVA_ONLY(X)
4270: 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 X.#else.# define
4280: 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 65 6e VVA_ONLY(X).#en
4290: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 41 dif../*.** The A
42a0: 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 LWAYS and NEVER
42b0: 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e 64 20 macros surround
42c0: 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 boolean expressi
42d0: 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20 61 72 ons which .** ar
42e0: 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 61 6c e intended to al
42f0: 77 61 79 73 20 62 65 20 74 72 75 65 20 6f 72 20 ways be true or
4300: 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74 69 76 false, respectiv
4310: 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20 65 78 ely. Such.** ex
4320: 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c 64 20 pressions could
4330: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 be omitted from
4340: 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c 65 74 the code complet
4350: 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79 0a 2a ely. But they.*
4360: 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 * are included i
4370: 6e 20 61 20 66 65 77 20 63 61 73 65 73 20 69 6e n a few cases in
4380: 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61 6e 63 order to enhanc
4390: 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e 63 65 e the resilience
43a0: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 74 6f .** of SQLite to
43b0: 20 75 6e 65 78 70 65 63 74 65 64 20 62 65 68 61 unexpected beha
43c0: 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 20 74 vior - to make t
43d0: 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d 68 65 he code "self-he
43e0: 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 64 75 aling".** or "du
43f0: 63 74 69 6c 65 22 20 72 61 74 68 65 72 20 74 68 ctile" rather th
4400: 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74 74 6c an being "brittl
4410: 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e 67 20 e" and crashing
4420: 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 at the first.**
4430: 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e 6e 65 hint of unplanne
4440: 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a d behavior..**.*
4450: 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
4460: 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 , ALWAYS and NEV
4470: 45 52 20 61 72 65 20 61 64 64 65 64 20 66 6f 72 ER are added for
4480: 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64 65 2e defensive code.
4490: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f 69 6e .**.** When doin
44a0: 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 g coverage testi
44b0: 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 ng ALWAYS and NE
44c0: 56 45 52 20 61 72 65 20 68 61 72 64 2d 63 6f 64 VER are hard-cod
44d0: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72 75 65 ed to.** be true
44e0: 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20 74 68 and false so th
44f0: 61 74 20 74 68 65 20 75 6e 72 65 61 63 68 61 62 at the unreachab
4500: 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73 70 65 le code then spe
4510: 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e 6f 74 cify will.** not
4520: 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73 20 75 be counted as u
4530: 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a 2a 2f ntested code..*/
4540: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c .#if defined(SQL
4550: 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 ITE_COVERAGE_TES
4560: 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 T).# define ALWA
4570: 59 53 28 58 29 20 20 20 20 20 20 28 31 29 0a 23 YS(X) (1).#
4580: 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 define NEVER(X)
4590: 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c 69 66 (0).#elif
45a0: 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 !defined(NDEBUG
45b0: 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 ).# define ALWAY
45c0: 53 28 58 29 20 20 20 20 20 20 28 28 58 29 3f 31 S(X) ((X)?1
45d0: 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29 29 0a :(assert(0),0)).
45e0: 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 # define NEVER(X
45f0: 29 20 20 20 20 20 20 20 28 28 58 29 3f 28 61 73 ) ((X)?(as
4600: 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a 23 65 sert(0),1):0).#e
4610: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 lse.# define ALW
4620: 41 59 53 28 58 29 20 20 20 20 20 20 28 58 29 0a AYS(X) (X).
4630: 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 # define NEVER(X
4640: 29 20 20 20 20 20 20 20 28 58 29 0a 23 65 6e 64 ) (X).#end
4650: 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e if../*.** Return
4660: 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
4670: 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 if the input is
4680: 20 61 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 a integer that
4690: 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a 2a 20 is too large.**
46a0: 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62 69 74 to fit in 32-bit
46b0: 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69 s. This macro i
46c0: 73 20 75 73 65 64 20 69 6e 73 69 64 65 20 6f 66 s used inside of
46d0: 20 76 61 72 69 6f 75 73 20 74 65 73 74 63 61 73 various testcas
46e0: 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 74 6f e().** macros to
46f0: 20 76 65 72 69 66 79 20 74 68 61 74 20 77 65 20 verify that we
4700: 68 61 76 65 20 74 65 73 74 65 64 20 53 51 4c 69 have tested SQLi
4710: 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66 69 6c te for large-fil
4720: 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 64 e support..*/.#d
4730: 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49 4e 54 efine IS_BIG_INT
4740: 28 58 29 20 20 28 28 28 58 29 26 7e 28 69 36 34 (X) (((X)&~(i64
4750: 29 30 78 66 66 66 66 66 66 66 66 29 21 3d 30 29 )0xffffffff)!=0)
4760: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 63 72 ../*.** The macr
4770: 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69 73 20 o unlikely() is
4780: 61 20 68 69 6e 74 20 74 68 61 74 20 73 75 72 72 a hint that surr
4790: 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61 6e 0a ounds a boolean.
47a0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 ** expression th
47b0: 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 66 61 at is usually fa
47c0: 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69 6b 65 lse. Macro like
47d0: 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73 0a 2a ly() surrounds.*
47e0: 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 * a boolean expr
47f0: 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 ession that is u
4800: 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20 47 43 sually true. GC
4810: 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 C is able to.**
4820: 75 73 65 20 74 68 65 73 65 20 68 69 6e 74 73 20 use these hints
4830: 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65 74 74 to generate bett
4840: 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74 69 6d er code, sometim
4850: 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e es..*/.#if defin
4860: 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 ed(__GNUC__) &&
4870: 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c 0.# define likel
4880: 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c 74 69 y(X) __builti
4890: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31 29 0a n_expect((X),1).
48a0: 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c # define unlikel
48b0: 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69 6e 5f y(X) __builtin_
48c0: 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a 23 65 expect((X),0).#e
48d0: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b lse.# define lik
48e0: 65 6c 79 28 58 29 20 20 20 20 21 21 28 58 29 0a ely(X) !!(X).
48f0: 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c # define unlikel
4900: 79 28 58 29 20 20 21 21 28 58 29 0a 23 65 6e 64 y(X) !!(X).#end
4910: 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a if../***********
4920: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 *** Include sqli
4930: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 te3.h in the mid
4940: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 dle of sqliteInt
4950: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
4960: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
4970: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 *** Begin file s
4980: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a qlite3.h *******
4990: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
49a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
49b0: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 **/./*.** 2001 S
49c0: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a eptember 15.**.*
49d0: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 * The author dis
49e0: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 claims copyright
49f0: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 to this source
4a00: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 code. In place
4a10: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f of.** a legal no
4a20: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 tice, here is a
4a30: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 blessing:.**.**
4a40: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f May you do go
4a50: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e od and not evil.
4a60: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 .** May you f
4a70: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 ind forgiveness
4a80: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 for yourself and
4a90: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e forgive others.
4aa0: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 .** May you s
4ab0: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 hare freely, nev
4ac0: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 er taking more t
4ad0: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a han you give..**
4ae0: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .***************
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 **********.** Th
4b30: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 is header file d
4b40: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
4b50: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51 face that the SQ
4b60: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 Lite library.**
4b70: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 presents to clie
4b80: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 nt programs. If
4b90: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 a C-function, s
4ba0: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 tructure, dataty
4bb0: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 pe,.** or consta
4bc0: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f nt definition do
4bd0: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e es not appear in
4be0: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e this file, then
4bf0: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 it is.** not a
4c00: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 published API of
4c10: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a SQLite, is subj
4c20: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
4c30: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c thout.** notice,
4c40: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 and should not
4c50: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 be referenced by
4c60: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 programs that u
4c70: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a se SQLite..**.**
4c80: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 Some of the def
4c90: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 initions that ar
4ca0: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 e in this file a
4cb0: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 re marked as.**
4cc0: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 "experimental".
4cd0: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e Experimental in
4ce0: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 terfaces are nor
4cf0: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 mally new.** fea
4d00: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 tures recently a
4d10: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 dded to SQLite.
4d20: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 We do not antic
4d30: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a ipate changes.**
4d40: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c to experimental
4d50: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 interfaces but
4d60: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68 reserve the righ
4d70: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 t to make minor
4d80: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 changes.** if ex
4d90: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 perience from us
4da0: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 e "in the wild"
4db0: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61 suggest such cha
4dc0: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 nges are prudent
4dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 ..**.** The offi
4de0: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 cial C-language
4df0: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f API documentatio
4e00: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 n for SQLite is
4e10: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 derived.** from
4e20: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 comments in this
4e30: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c file. This fil
4e40: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 e is the authori
4e50: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a tative source.**
4e60: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 on how SQLite i
4e70: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75 nterfaces are su
4e80: 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 ppose to operate
4e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 ..**.** The name
4ea0: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e of this file un
4eb0: 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f der configuratio
4ec0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 n management is
4ed0: 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a "sqlite.h.in"..*
4ee0: 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d * The makefile m
4ef0: 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 akes some minor
4f00: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 changes to this
4f10: 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e file (such as in
4f20: 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 serting.** the v
4f30: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 ersion number) a
4f40: 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e nd changes its n
4f50: 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e ame to "sqlite3.
4f60: 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 h" as.** part of
4f70: 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 the build proce
4f80: 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f ss..*/.#ifndef _
4f90: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 SQLITE3_H_.#defi
4fa0: 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 ne _SQLITE3_H_.#
4fb0: 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e include <stdarg.
4fc0: 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 h> /* Needed
4fd0: 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 for the definit
4fe0: 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a ion of va_list *
4ff0: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 /../*.** Make su
5000: 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 re we can call t
5010: 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 his stuff from C
5020: 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 ++..*/.#if 0.ext
5030: 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 ern "C" {.#endif
5040: 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 .../*.** Add the
5050: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 ability to over
5060: 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f ride 'extern'.*/
5070: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
5080: 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 EXTERN.# define
5090: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 SQLITE_EXTERN ex
50a0: 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66 tern.#endif..#if
50b0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a ndef SQLITE_API.
50c0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
50d0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a API.#endif.../*.
50e0: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d ** These no-op m
50f0: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 acros are used i
5100: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 n front of inter
5110: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 faces to mark th
5120: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ose.** interface
5130: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72 s as either depr
5140: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 ecated or experi
5150: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 mental. New app
5160: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
5170: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 uld not use depr
5180: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 ecated interface
5190: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
51a0: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 port for backwar
51b0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
51c0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
51d0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
51e0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
51f0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
5200: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
5210: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
5220: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
5230: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
5240: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
5250: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
5260: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
5270: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
5280: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
5290: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
52a0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
52b0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
52c0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
52d0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
52e0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
52f0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
5300: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
5310: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
5320: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
5330: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
5340: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
5350: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
5360: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
5370: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
5380: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
5390: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
53a0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
53b0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
53c0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
53d0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
53e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
53f0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
5400: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
5410: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
5420: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
5430: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
5440: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
5450: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
5460: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
5470: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
5480: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
5490: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
54a0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
54b0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
54c0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
54d0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
54e0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
54f0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
5500: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
5510: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
5520: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
5530: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
5540: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
5550: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
5560: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
5570: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
5580: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
5590: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
55a0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
55b0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
55c0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
55d0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
55e0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
55f0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
5600: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
5610: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
5620: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
5630: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
5640: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
5650: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
5660: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
5670: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
5680: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
5690: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
56a0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
56b0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
56c0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
56d0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
56e0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
56f0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
5700: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
5710: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
5720: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
5730: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
5740: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
5750: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
5760: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
5770: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
5780: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
5790: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
57a0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
57b0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
57c0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
57d0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
57e0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
57f0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
5800: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
5810: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
5820: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
5830: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
5840: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
5850: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
5860: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
5870: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
5880: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
5890: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
58a0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
58b0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
58c0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
58d0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
58e0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
58f0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
5900: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
5910: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
5920: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
5930: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
5940: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
5950: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
5960: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
5970: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
5980: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
5990: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
59a0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
59b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
59c0: 20 20 20 20 20 22 33 2e 37 2e 36 2e 33 22 0a 23 "3.7.6.3".#
59d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
59e0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 RSION_NUMBER 300
59f0: 37 30 30 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 7006.#define SQL
5a00: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 ITE_SOURCE_ID
5a10: 20 20 20 22 32 30 31 31 2d 30 35 2d 31 39 20 31 "2011-05-19 1
5a20: 33 3a 32 36 3a 35 34 20 65 64 31 64 61 35 31 30 3:26:54 ed1da510
5a30: 61 32 33 39 65 61 37 36 37 61 30 31 64 63 33 33 a239ea767a01dc33
5a40: 32 62 36 36 37 31 31 39 66 61 33 63 39 30 38 65 2b667119fa3c908e
5a50: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 "../*.** CAPI3RE
5a60: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
5a70: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
5a80: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ers.** KEYWORDS:
5a90: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
5aa0: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 , sqlite3_source
5ab0: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 id.**.** These i
5ac0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 nterfaces provid
5ad0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
5ae0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
5af0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a QLITE_VERSION],.
5b00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
5b10: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 ON_NUMBER], and
5b20: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 [SQLITE_SOURCE_I
5b30: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f D] C preprocesso
5b40: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 r macros.** but
5b50: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 are associated w
5b60: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 ith the library
5b70: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 instead of the h
5b80: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 eader file. ^(C
5b90: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 autious.** progr
5ba0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 ammers might inc
5bb0: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 lude assert() st
5bc0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 atements in thei
5bd0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f r application to
5be0: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 .** verify that
5bf0: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
5c00: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 by these interfa
5c10: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 ces match the ma
5c20: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 cros in.** the h
5c30: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 eader, and thus
5c40: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
5c50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a application is.*
5c60: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
5c70: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 matching library
5c80: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 and header file
5c90: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s..**.** <blockq
5ca0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 uote><pre>.** as
5cb0: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 sert( sqlite3_li
5cc0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
5cd0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f )==SQLITE_VERSIO
5ce0: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 N_NUMBER );.** a
5cf0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
5d00: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
5d10: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 ,SQLITE_SOURCE_I
5d20: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 D)==0 );.** asse
5d30: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 rt( strcmp(sqlit
5d40: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c e3_libversion(),
5d50: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d SQLITE_VERSION)=
5d60: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c =0 );.** </pre><
5d70: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
5d80: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
5d90: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
5da0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 ng constant cont
5db0: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 ains the text of
5dc0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
5dd0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 ].** macro. ^Th
5de0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
5df0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 sion() function
5e00: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
5e10: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 r to the.** to t
5e20: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
5e30: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
5e40: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 tant. The sqlit
5e50: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a e3_libversion().
5e60: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 ** function is p
5e70: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 rovided for use
5e80: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c in DLLs since DL
5e90: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 L users usually
5ea0: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 do not have.** d
5eb0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 irect access to
5ec0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 string constants
5ed0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e within the DLL.
5ee0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
5ef0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
5f00: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ber() function r
5f10: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
5f20: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 r equal to.** [S
5f30: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
5f40: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c MBER]. ^The sql
5f50: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
5f60: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
5f70: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
5f80: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
5f90: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
5fa0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
5fb0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
5fc0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
5fd0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a rocessor macro..
5fe0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
5ff0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
6000: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
6010: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
6020: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
6030: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 char sqlite3_ve
6040: 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 rsion[] = SQLITE
6050: 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 _VERSION;.SQLITE
6060: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
6070: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 *sqlite3_libvers
6080: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ion(void);.SQLIT
6090: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
60a0: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 *sqlite3_source
60b0: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 id(void);.SQLITE
60c0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
60d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
60e0: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a er(void);../*.**
60f0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
6100: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 ime Library Comp
6110: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 ilation Options
6120: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a Diagnostics.**.*
6130: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
6140: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
6150: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 d() function ret
6160: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 urns 0 or 1 .**
6170: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 indicating wheth
6180: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 er the specified
6190: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 option was defi
61a0: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 ned at .** compi
61b0: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 le time. ^The S
61c0: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 QLITE_ prefix ma
61d0: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f y be omitted fro
61e0: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e m the .** option
61f0: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 name passed to
6200: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
6210: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a ption_used(). .
6220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
6230: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
6240: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 _get() function
6250: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 allows iterating
6260: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 .** over the lis
6270: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 t of options tha
6280: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 t were defined a
6290: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 t compile time b
62a0: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 y.** returning t
62b0: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 he N-th compile
62c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 time option stri
62d0: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 ng. ^If N is ou
62e0: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 t of range,.** s
62f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
6300: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 tion_get() retur
6310: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
6320: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f r. ^The SQLITE_
6330: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f .** prefix is o
6340: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 mitted from any
6350: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
6360: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
6370: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
6380: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 t()..**.** ^Supp
6390: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 ort for the diag
63a0: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 nostic functions
63b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
63c0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a option_used().**
63d0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d and sqlite3_com
63e0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
63f0: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 may be omitted
6400: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 by specifying th
6410: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d e .** [SQLITE_OM
6420: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
6430: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 _DIAGS] option a
6440: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a t compile time..
6450: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
6460: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 SQL functions [s
6470: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 qlite_compileopt
6480: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ion_used()] and.
6490: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 ** [sqlite_compi
64a0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 leoption_get()]
64b0: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 and the [compile
64c0: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d _options pragma]
64d0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
64e0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
64f0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c OPTION_DIAGS.SQL
6500: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
6510: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
6520: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 n_used(const cha
6530: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 r *zOptName);.SQ
6540: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
6550: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
6560: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
6570: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
6590: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
65a0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
65b0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
65c0: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
65d0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
65e0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
65f0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
6600: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
6610: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 led mutexing cod
6620: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f e omitted due to
6630: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
6640: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 THREADSAFE] comp
6650: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
6660: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a being set to 0..
6670: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e **.** SQLite can
6680: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 be compiled wit
6690: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 h or without mut
66a0: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 exes. When.** t
66b0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
66c0: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 DSAFE] C preproc
66d0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 essor macro is 1
66e0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a or 2, mutexes.*
66f0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e * are enabled an
6700: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 d SQLite is thre
6710: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 adsafe. When th
6720: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
6730: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 EADSAFE] macro i
6740: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 s 0, .** the mut
6750: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 exes are omitted
6760: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d . Without the m
6770: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f utexes, it is no
6780: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 t safe.** to use
6790: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 SQLite concurre
67a0: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 ntly from more t
67b0: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a han one thread..
67c0: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d **.** Enabling m
67d0: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 utexes incurs a
67e0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f measurable perfo
67f0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a rmance penalty..
6800: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 ** So if speed i
6810: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f s of utmost impo
6820: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 rtance, it makes
6830: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c sense to disabl
6840: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 e.** the mutexes
6850: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d . But for maxim
6860: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 um safety, mutex
6870: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 es should be ena
6880: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 bled..** ^The de
6890: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
68a0: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f s for mutexes to
68b0: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a be enabled..**.
68c0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
68d0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 e can be used by
68e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
68f0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
6900: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e t the.** version
6910: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 of SQLite that
6920: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 it is linking ag
6930: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c ainst was compil
6940: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 ed with.** the d
6950: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f esired setting o
6960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 f the [SQLITE_TH
6970: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e READSAFE] macro.
6980: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
6990: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 rface only repor
69a0: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ts on the compil
69b0: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 e-time mutex set
69c0: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ting.** of the [
69d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
69e0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c E] flag. If SQL
69f0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
6a00: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 with.** SQLITE_T
6a10: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d HREADSAFE=1 or =
6a20: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 2 then mutexes a
6a30: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
6a40: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
6a50: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
6a60: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
6a70: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
6a80: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
6a90: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
6aa0: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
6ab0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
6ac0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
6ad0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
6ae0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
6af0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 NFIG_MUTEX]. ^(
6b00: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
6b10: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 of the.** sqlit
6b20: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
6b30: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f function shows o
6b40: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d nly the compile-
6b50: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a time setting of.
6b60: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 ** thread safety
6b70: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 , not any run-ti
6b80: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 me changes to th
6b90: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 at setting made
6ba0: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f by.** sqlite3_co
6bb0: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 nfig(). In other
6bc0: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 words, the retu
6bd0: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
6be0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
6bf0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 ().** is unchang
6c00: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 ed by calls to s
6c10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e qlite3_config().
6c20: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 )^.**.** See the
6c30: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
6c40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
6c50: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
6c60: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 nformation..*/.S
6c70: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
6c80: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
6c90: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
6ca0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
6cb0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
6cc0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a dle.** KEYWORDS:
6cd0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
6ce0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
6cf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
6d00: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
6d10: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
6d20: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
6d30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
6d40: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
6d50: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
6d60: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
6d70: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
6d80: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
6d90: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
6da0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
6db0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
6dc0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
6dd0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
6de0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
6df0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
6e00: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
6e10: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
6e20: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
6e30: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
6e40: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
6e50: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
6e60: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
6e70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
6e80: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
6e90: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
6ea0: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
6eb0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
6ec0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
6ed0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
6ee0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
6ef0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
6f00: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
6f10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
6f20: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
6f30: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
6f40: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a Integer Types.**
6f50: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
6f60: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 e_int64 sqlite_u
6f70: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 int64.**.** Beca
6f80: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 use there is no
6f90: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 cross-platform w
6fa0: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 ay to specify 64
6fb0: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 -bit integer typ
6fc0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 es.** SQLite inc
6fd0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 ludes typedefs f
6fe0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 or 64-bit signed
6ff0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e and unsigned in
7000: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 tegers..**.** Th
7010: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
7020: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 and sqlite3_uint
7030: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 64 are the prefe
7040: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 rred type defini
7050: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 tions..** The sq
7060: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 lite_int64 and s
7070: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 qlite_uint64 typ
7080: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 es are supported
7090: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a for backwards.*
70a0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 * compatibility
70b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 only..**.** ^The
70c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
70d0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 nd sqlite_int64
70e0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 types can store
70f0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a integer values.*
7100: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 * between -92233
7110: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 72036854775808 a
7120: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 nd +922337203685
7130: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 4775807 inclusiv
7140: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 e. ^The.** sqli
7150: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 te3_uint64 and s
7160: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 qlite_uint64 typ
7170: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
7180: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 eger values .**
7190: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 between 0 and +1
71a0: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 8446744073709551
71b0: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 615 inclusive..*
71c0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
71d0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 INT64_TYPE. typ
71e0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 edef SQLITE_INT6
71f0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 4_TYPE sqlite_in
7200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
7210: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 nsigned SQLITE_I
7220: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 NT64_TYPE sqlite
7230: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 _uint64;.#elif d
7240: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 efined(_MSC_VER)
7250: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f || defined(__BO
7260: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 RLANDC__). type
7270: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 def __int64 sqli
7280: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
7290: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 def unsigned __i
72a0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
72b0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64;.#else. type
72c0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e def long long in
72d0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a t sqlite_int64;.
72e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
72f0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ed long long int
7300: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
7310: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 #endif.typedef s
7320: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
7330: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 te3_int64;.typed
7340: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 ef sqlite_uint64
7350: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b sqlite3_uint64;
7360: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 ../*.** If compi
7370: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 ling for a proce
7380: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 ssor that lacks
7390: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
73a0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 upport,.** subst
73b0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f itute integer fo
73c0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 r floating-point
73d0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
73e0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 TE_OMIT_FLOATING
73f0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 _POINT.# define
7400: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 double sqlite3_i
7410: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a nt64.#endif../*.
7420: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
7430: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 sing A Database
7440: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a Connection.**.**
7450: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
7460: 6f 73 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ose() routine is
7470: 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
7480: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
7490: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 ] object..** ^Ca
74a0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
74b0: 6c 6f 73 65 28 29 20 72 65 74 75 72 6e 20 53 51 lose() return SQ
74c0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 20 5b LITE_OK if the [
74d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
74e0: 69 73 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c is.** successful
74f0: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 ly destroyed and
7500: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 all associated
7510: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 resources are de
7520: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a allocated..**.**
7530: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 Applications mu
7540: 73 74 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 st [sqlite3_fina
7550: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d lize | finalize]
7560: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
7570: 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e tatements].** an
7580: 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
7590: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 close | close] a
75a0: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 ll [BLOB handles
75b0: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 ] associated wit
75c0: 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 h.** the [sqlite
75d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
75e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
75f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
7600: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
7610: 65 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 e3_close() is ca
7620: 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 lled on a [datab
7630: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
7640: 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a that still has.*
7650: 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 * outstanding [p
7660: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
7670: 74 73 5d 20 6f 72 20 5b 42 4c 4f 42 20 68 61 6e ts] or [BLOB han
7680: 64 6c 65 73 5d 2c 20 74 68 65 6e 20 69 74 20 72 dles], then it r
7690: 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 eturns.** SQLITE
76a0: 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 _BUSY..**.** ^If
76b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
76c0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 )] is invoked wh
76d0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
76e0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
76f0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
7700: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
7710: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
7720: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
7730: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
7740: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 ose(C)] must be
7750: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
7760: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
7770: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
7780: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
7790: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
77a0: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
77b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
77c0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
77d0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
77e0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
77f0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 sed..** ^Calling
7800: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
7810: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
7820: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 69 73 nter argument is
7830: 20 61 20 0a 2a 2a 20 68 61 72 6d 6c 65 73 73 20 a .** harmless
7840: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 no-op..*/.SQLITE
7850: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
7860: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a _close(sqlite3 *
7870: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
7880: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
7890: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
78a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
78b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
78c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
78d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
78e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
78f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
7900: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
7910: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
7920: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
7930: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
7940: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
7950: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
7960: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
7970: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 erface.**.** The
7980: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
7990: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 interface is a c
79a0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 onvenience wrapp
79b0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
79c0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
79d0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
79e0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
79f0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c te3_finalize()],
7a00: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 .** that allows
7a10: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
7a20: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 o run multiple s
7a30: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c tatements of SQL
7a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 .** without havi
7a50: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 ng to use a lot
7a60: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a of C code. .**.*
7a70: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
7a80: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
7a90: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 runs zero or mor
7aa0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c e UTF-8 encoded,
7ab0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
7ac0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 parate SQL state
7ad0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
7ae0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 o its 2nd argume
7af0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f nt,.** in the co
7b00: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
7b10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7b20: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 n] passed in as
7b30: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d its 1st.** argum
7b40: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ent. ^If the ca
7b50: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
7b60: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d of the 3rd argum
7b70: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ent to.** sqlite
7b80: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
7b90: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 NULL, then it is
7ba0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 invoked for eac
7bb0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 h result row.**
7bc0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 coming out of th
7bd0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 e evaluated SQL
7be0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 statements. ^Th
7bf0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
7c00: 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f o.** to sqlite3_
7c10: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
7c20: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
7c30: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
7c40: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
7c50: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
7c60: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
7c70: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
7c80: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
7c90: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
7ca0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
7cb0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
7cc0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
7cd0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
7ce0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
7cf0: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
7d00: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
7d10: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
7d20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
7d30: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
7d40: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
7d50: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
7d60: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
7d70: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
7d80: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
7d90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
7da0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
7db0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
7dc0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
7dd0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
7de0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
7df0: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
7e00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
7e10: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
7e20: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
7e30: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
7e40: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
7e50: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
7e60: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
7e70: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
7e80: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
7e90: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
7ea0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
7eb0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
7ec0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f arameter of.** o
7ed0: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
7ee0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 after the error
7ef0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
7f00: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 is no longer nee
7f10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ded..** ^If the
7f20: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
7f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
7f40: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
7f50: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 no errors.** occ
7f60: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ur, then sqlite3
7f70: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 _exec() sets the
7f80: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 pointer in its
7f90: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
7fa0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 .** NULL before
7fb0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
7fc0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f ^If an sqlite3_
7fd0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
7fe0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
7ff0: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 , the sqlite3_ex
8000: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 ec().** routine
8010: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 returns SQLITE_A
8020: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 BORT without inv
8030: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
8040: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 ck again and.**
8050: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 without running
8060: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 any subsequent S
8070: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
8080: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 *.** ^The 2nd ar
8090: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
80a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
80b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 lback function i
80c0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
80d0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
80e0: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 e result. ^The
80f0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3rd argument to
8100: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
8110: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ().** callback i
8120: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
8130: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
8140: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 s obtained as if
8150: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
8160: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
8170: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 , one for each c
8180: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 olumn. ^If an e
8190: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 lement of a.** r
81a0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c esult row is NUL
81b0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 L then the corre
81c0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 sponding string
81d0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a pointer for the.
81e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
81f0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 ) callback is a
8200: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
8210: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
8220: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 to the.** sqlit
8230: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
8240: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
8250: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
8260: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 rings where each
8270: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 .** entry repres
8280: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 ents the name of
8290: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 corresponding r
82a0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 esult column as
82b0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
82c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
82d0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _name()]..**.**
82e0: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 ^If the 2nd para
82f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
8300: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c _exec() is a NUL
8310: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 L pointer, a poi
8320: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d nter.** to an em
8330: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 pty string, or a
8340: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f pointer that co
8350: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 ntains only whit
8360: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a espace and/or .*
8370: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 * SQL comments,
8380: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 then no SQL stat
8390: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
83a0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 ated and the dat
83b0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 abase.** is not
83c0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 changed..**.** R
83d0: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a estrictions:.**.
83e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
83f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
8400: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
8410: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
8420: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
8430: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 ec().** is
8440: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e a valid and open
8450: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
8460: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 ction]..** <li>
8470: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
8480: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b must not close [
8490: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
84a0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
84b0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 y.** the 1s
84c0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
84d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
84e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
84f0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
8500: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
8510: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
8520: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 modify the SQL s
8530: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 tatement text pa
8540: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 ssed into.**
8550: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 the 2nd parame
8560: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 ter of sqlite3_e
8570: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
8580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
8590: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a nning..** </ul>.
85a0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
85b0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
85c0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
85e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
85f0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
8600: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
8610: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
8620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8630: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
8640: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
8650: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
8660: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
8670: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
8680: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
8690: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
86b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
86c0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
86d0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
86e0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **errmsg
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8700: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
8710: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
8720: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
8730: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
8740: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
8750: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
8760: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
8770: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
8780: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
8790: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
87a0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
87b0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
87c0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
87d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
87e0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
87f0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
8800: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
8810: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
8820: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
8830: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
8840: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
8850: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
8860: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
8870: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
8880: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
8890: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
88a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
88b0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
88c0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
88d0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
88e0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
88f0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
8900: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
8910: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
8920: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
8930: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
8940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
8950: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
8960: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
8970: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
8980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8990: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
89a0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
89b0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
89c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
89d0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
89e0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
89f0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
8a00: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
8a10: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
8a20: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
8a30: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
8a40: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
8a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
8a60: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
8a70: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
8a80: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
8a90: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
8aa0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
8ab0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
8ac0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
8ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
8ae0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
8af0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
8b00: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
8b10: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
8b20: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
8b30: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
8b40: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
8b50: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
8b60: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
8b70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
8b80: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
8b90: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
8ba0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
8bb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8bc0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
8bd0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
8be0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
8bf0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
8c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
8c10: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
8c20: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 * Unknown opcode
8c30: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 in sqlite3_file
8c40: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 _control() */.#d
8c50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c efine SQLITE_FUL
8c60: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a L 13 /*
8c70: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 Insertion faile
8c80: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 d because databa
8c90: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 se is full */.#d
8ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
8cb0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a TOPEN 14 /*
8cc0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 Unable to open
8cd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
8ce0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
8cf0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 ITE_PROTOCOL
8d00: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 15 /* Database
8d10: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 lock protocol e
8d20: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
8d30: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 SQLITE_EMPTY
8d40: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 16 /* Datab
8d50: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a ase is empty */.
8d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
8d70: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 CHEMA 17
8d80: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
8d90: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a schema changed *
8da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8db0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 _TOOBIG 18
8dc0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 /* String or B
8dd0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 LOB exceeds size
8de0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e limit */.#defin
8df0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
8e00: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f INT 19 /* Abo
8e10: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 rt due to constr
8e20: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
8e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8e40: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
8e50: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
8e60: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
8e70: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
8e80: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
8e90: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
8ea0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
8eb0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
8ec0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
8ed0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
8ee0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
8ef0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
8f00: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
8f10: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
8f20: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
8f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8f40: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
8f50: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
8f60: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
8f70: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
8f80: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
8f90: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
8fa0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
8fb0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
8fc0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
8fd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
8fe0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
8ff0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
9000: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
9010: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
9020: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 QLITE_ROW
9030: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 100 /* sqlite
9040: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 3_step() has ano
9050: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
9060: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
9070: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
9080: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
9090: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 p() has finished
90a0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a executing */./*
90b0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f end-of-error-co
90c0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 des */../*.** CA
90d0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 PI3REF: Extended
90e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
90f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
9100: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d nded error code}
9110: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
9120: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f codes}.** KEYWO
9130: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
9140: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 esult code} {ext
9150: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
9160: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 es}.**.** In its
9170: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
9180: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
9190: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
91a0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
91b0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
91c0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
91d0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 s]. However, ex
91e0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
91f0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a wn that many of.
9200: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 ** these result
9210: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
9220: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 arse-grained. T
9230: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
9240: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
9250: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
9260: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 problems as prog
9270: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 rammers might li
9280: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
9290: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
92a0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
92b0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
92c0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
92d0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
92e0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
92f0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
9300: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
9310: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
9320: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
9330: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
9340: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
9350: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e ult codes are en
9360: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
9370: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
9380: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
9390: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
93a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
93b0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
93c0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a des()] API..**.*
93d0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 * Some of the av
93e0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 ailable extended
93f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
9400: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a e listed here..*
9410: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 * One may expect
9420: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
9430: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
9440: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 odes will be exp
9450: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 and.** over time
9460: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
9470: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 uses extended r
9480: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 esult codes shou
9490: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 ld expect.** to
94a0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 see new result c
94b0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 odes in future r
94c0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
94d0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c e..**.** The SQL
94e0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f ITE_OK result co
94f0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 de will never be
9500: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 extended. It w
9510: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 ill always.** be
9520: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a exactly zero..*
9530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
9540: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
9550: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
9560: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
9570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9580: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
9590: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
95a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
95b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
95c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
95d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
95e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
95f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9600: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
9610: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9620: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
9630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
9640: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
9650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
9660: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
9670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
9680: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
9690: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
96a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
96b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
96c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
96d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
96e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
96f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
9700: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
9710: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
9720: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
9730: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
9740: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
9750: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
9760: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
9770: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
9780: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
9790: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
97a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
97b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
97c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
97d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
97e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
97f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
9800: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
9810: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9820: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
9830: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
9840: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
9850: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9860: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
9870: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
9880: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
9890: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
98a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
98b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
98c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
98d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
98e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
98f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
9900: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
9910: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9920: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
9930: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
9940: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
9950: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9960: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
9970: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
9980: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
9990: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
99a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
99b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
99c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
99d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
99e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
99f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
9a00: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
9a10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9a20: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
9a30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
9a40: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
9a50: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
9a60: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
9a70: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 e SQLITE_BUSY_RE
9a80: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 COVERY
9a90: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
9aa0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
9ab0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
9ac0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 EN_NOTEMPDIR
9ad0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
9ae0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a EN | (1<<8))../*
9af0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
9b00: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 ags For File Ope
9b10: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a n Operations.**.
9b20: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c ** These bit val
9b30: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 ues are intended
9b40: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a for use in the.
9b50: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ** 3rd parameter
9b60: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
9b70: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
9b80: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 rface and.** in
9b90: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
9ba0: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d r to the xOpen m
9bb0: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 ethod of the.**
9bc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
9bd0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
9be0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
9bf0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 DONLY 0x
9c00: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 00000001 /* Ok
9c10: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
9c20: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
9c30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
9c40: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 DWRITE 0x
9c50: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 00000002 /* Ok
9c60: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
9c70: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
9c80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
9c90: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 ATE 0x
9ca0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 00000004 /* Ok
9cb0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
9cc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
9cd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c SQLITE_OPEN_DEL
9ce0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 ETEONCLOSE 0x
9cf0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 00000008 /* VFS
9d00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9d10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
9d20: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 LUSIVE 0x
9d30: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 00000010 /* VFS
9d40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 SQLITE_OPEN_AUT
9d60: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 OPROXY 0x
9d70: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 00000020 /* VFS
9d80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9d90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
9da0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 N_DB 0x
9db0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 00000100 /* VFS
9dc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9dd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
9de0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 P_DB 0x
9df0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 00000200 /* VFS
9e00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9e10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 SQLITE_OPEN_TRA
9e20: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 NSIENT_DB 0x
9e30: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 00000400 /* VFS
9e40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9e50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
9e60: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 N_JOURNAL 0x
9e70: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 00000800 /* VFS
9e80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9e90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
9ea0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 P_JOURNAL 0x
9eb0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 00001000 /* VFS
9ec0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9ed0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 SQLITE_OPEN_SUB
9ee0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 JOURNAL 0x
9ef0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 00002000 /* VFS
9f00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9f10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 SQLITE_OPEN_MAS
9f20: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 TER_JOURNAL 0x
9f30: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 00004000 /* VFS
9f40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
9f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d SQLITE_OPEN_NOM
9f60: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 UTEX 0x
9f70: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 00008000 /* Ok
9f80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
9f90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
9fa0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c SQLITE_OPEN_FUL
9fb0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 LMUTEX 0x
9fc0: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 00010000 /* Ok
9fd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
9fe0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
9ff0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
a000: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 REDCACHE 0x
a010: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 00020000 /* Ok
a020: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
a030: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
a040: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
a050: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 VATECACHE 0x
a060: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 00040000 /* Ok
a070: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
a080: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 _v2() */.#define
a090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c SQLITE_OPEN_WAL
a0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
a0b0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 00080000 /* VFS
a0c0: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 only */../* Res
a0d0: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 erved:
a0e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
a0f0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a x00F00000 */../*
a100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
a110: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 vice Characteris
a120: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 tics.**.** The x
a130: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
a140: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 stics method of
a150: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
a160: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 methods].** obje
a170: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e ct returns an in
a180: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 teger which is a
a190: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 vector of the t
a1a0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 hese.** bit valu
a1b0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f es expressing I/
a1c0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 O characteristic
a1d0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 s of the mass st
a1e0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 orage.** device
a1f0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 that holds the f
a200: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 ile that the [sq
a210: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
a220: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a ].** refers to..
a230: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
a240: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
a250: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
a260: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
a270: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
a280: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
a290: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a2a0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
a2b0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
a2c0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
a2d0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
a2e0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
a2f0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
a300: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
a310: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
a320: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
a330: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
a340: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
a350: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
a360: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
a370: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
a380: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
a390: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
a3a0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
a3b0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
a3c0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
a3d0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
a3e0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
a3f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
a400: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
a410: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
a420: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
a430: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
a440: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
a450: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
a460: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a to xWrite()..*/.
a470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
a480: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
a490: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
a4a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
a4b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
a4c0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
a4d0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
a4e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
a4f0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
a500: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
a510: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
a520: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a530: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
a540: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
a550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
a560: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
a570: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
a580: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
a590: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
a5a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
a5b0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
a5c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
a5d0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
a5e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
a5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a600: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
a610: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
a620: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
a630: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a640: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
a650: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
a660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
a670: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
a680: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
a690: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
a6a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
a6b0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
a6c0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
a6d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
a6e0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
a6f0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
a700: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 800../*.** CAPI3
a710: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e REF: File Lockin
a720: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 g Levels.**.** S
a730: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f QLite uses one o
a740: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
a750: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
a760: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 cond.** argument
a770: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b to calls it mak
a780: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 es to the xLock(
a790: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
a7a0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e methods.** of an
a7b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
a7c0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f hods] object..*/
a7d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a7e0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 LOCK_NONE
a7f0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
a800: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 ITE_LOCK_SHARED
a810: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
a820: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
a830: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 ERVED 2.#de
a840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
a850: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 _PENDING 3
a860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a870: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 LOCK_EXCLUSIVE
a880: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4../*.** CAPI
a890: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 3REF: Synchroniz
a8a0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 ation Type Flags
a8b0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 .**.** When SQLi
a8c0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 te invokes the x
a8d0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 Sync() method of
a8e0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
a8f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
a900: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d ct it uses a com
a910: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 bination of.** t
a920: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
a930: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
a940: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
a950: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 * When the SQLIT
a960: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
a970: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 flag is used, it
a980: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a means that the.
a990: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f ** sync operatio
a9a0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 n only needs to
a9b0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 flush data to ma
a9c0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f ss storage. Ino
a9d0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f de.** informatio
a9e0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c n need not be fl
a9f0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f ushed. If the lo
aa00: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 wer four bits of
aa10: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 the flag.** equ
aa20: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e al SQLITE_SYNC_N
aa30: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e ORMAL, that mean
aa40: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 s to use normal
aa50: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 fsync() semantic
aa60: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 s..** If the low
aa70: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 er four bits equ
aa80: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 al SQLITE_SYNC_F
aa90: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a ULL, that means.
aaa0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 ** to use Mac OS
aab0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e X style fullsyn
aac0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 c instead of fsy
aad0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e nc()..**.** Do n
aae0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 ot confuse the S
aaf0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
ab00: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e L and SQLITE_SYN
ab10: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 C_FULL flags.**
ab20: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 with the [PRAGMA
ab30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f synchronous]=NO
ab40: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 RMAL and [PRAGMA
ab50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 synchronous]=FU
ab60: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 LL.** settings.
ab70: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 The [synchronou
ab80: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d s pragma] determ
ab90: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 ines when calls
aba0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 to the.** xSync
abb0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 VFS method occur
abc0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 and applies uni
abd0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c formly across al
abe0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 l platforms..**
abf0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f The SQLITE_SYNC_
ac00: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
ac10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
ac20: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a s determine how.
ac30: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 ** energetic or
ac40: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 rigorous or forc
ac50: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 eful the sync op
ac60: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 erations are and
ac70: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 .** only make a
ac80: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 difference on Ma
ac90: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 c OSX for the de
aca0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 fault SQLite cod
acb0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 e..** (Third-par
acc0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ty VFS implement
acd0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 ations might als
ace0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 o make the disti
acf0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 nction.** betwee
ad00: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f n SQLITE_SYNC_NO
ad10: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
ad20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 SYNC_FULL, but a
ad30: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 mong the.** oper
ad40: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 ating systems na
ad50: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 tively supported
ad60: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 by SQLite, only
ad70: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 Mac OSX.** care
ad80: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 s about the diff
ad90: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 erence.).*/.#def
ada0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
adb0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
adc0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
add0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
ade0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
adf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
ae00: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
ae10: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
ae20: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
ae30: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
ae40: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 e Handle.**.** A
ae50: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
ae60: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
ae70: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 ts an open file
ae80: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 in the .** [sqli
ae90: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 te3_vfs | OS int
aea0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 erface layer].
aeb0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e Individual OS in
aec0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 terface.** imple
aed0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a mentations will.
aee0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c ** want to subcl
aef0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 ass this object
af00: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 by appending add
af10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a itional fields.*
af20: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 * for their own
af30: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f use. The pMetho
af40: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f ds entry is a po
af50: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b inter to an.** [
af60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
af70: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ds] object that
af80: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 defines methods
af90: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a for performing.*
afa0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 * I/O operations
afb0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c on the open fil
afc0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 e..*/.typedef st
afd0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
afe0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a e sqlite3_file;.
aff0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
b000: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 ile {. const st
b010: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
b020: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 methods *pMethod
b030: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 s; /* Methods f
b040: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 or an open file
b050: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
b060: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
b070: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c ace File Virtual
b080: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a Methods Object.
b090: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
b0a0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
b0b0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 sqlite3_vfs] xOp
b0c0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 en method popula
b0d0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
b0e0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
b0f0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
b100: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
b110: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
b120: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
b130: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
b140: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
b150: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
b160: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
b170: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
b180: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
b190: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
b1a0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
b1b0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
b1c0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
b1d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
b1e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 bject..**.** If
b1f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
b200: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
b210: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
b220: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
b230: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
b240: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
b250: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
b260: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
b270: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
b280: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e ven if the xOpen
b290: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
b2a0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
b2b0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
b2c0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
b2d0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
b2e0: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a a failed xOpen.
b2f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f ** is for the xO
b300: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73 pen to set the s
b310: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
b320: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 hods element to
b330: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
b340: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
b350: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
b360: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
b370: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
b380: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
b390: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
b3a0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
b3b0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
b3c0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
b3d0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
b3e0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
b3f0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
b400: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
b410: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
b420: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
b430: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
b440: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
b450: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
b460: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
b470: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
b480: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
b490: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
b4a0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
b4b0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
b4c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
b4d0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
b4e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
b4f0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
b500: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
b510: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
b520: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
b530: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
b540: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
b550: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
b560: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
b570: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
b580: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
b590: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
b5a0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
b5b0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
b5c0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
b5d0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
b5e0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
b5f0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
b600: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
b610: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
b620: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
b630: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
b640: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
b650: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
b660: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
b670: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
b680: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
b690: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
b6a0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
b6b0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
b6c0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
b6d0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
b6e0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
b6f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
b700: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
b710: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
b720: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
b730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
b740: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
b750: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
b760: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
b770: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
b780: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
b790: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
b7a0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
b7b0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
b7c0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
b7d0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
b7e0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
b7f0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
b800: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
b810: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
b820: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
b830: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
b840: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
b850: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
b860: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
b870: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
b880: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
b890: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
b8a0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
b8b0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
b8c0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
b8d0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
b8e0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
b8f0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
b900: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
b910: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
b920: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
b930: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
b940: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
b950: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
b960: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
b970: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
b980: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
b990: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
b9a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
b9b0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
b9c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
b9d0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
b9e0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
b9f0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
ba00: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
ba10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
ba20: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
ba30: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
ba40: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
ba50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
ba60: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
ba70: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
ba80: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
ba90: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
baa0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
bab0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
bac0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
bad0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
bae0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
baf0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
bb00: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
bb10: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
bb20: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
bb30: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
bb40: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
bb50: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
bb60: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
bb70: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
bb80: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
bb90: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
bba0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
bbb0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
bbc0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
bbd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
bbe0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
bbf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
bc00: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
bc10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
bc20: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
bc30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
bc40: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
bc50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
bc60: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
bc70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
bc80: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
bc90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
bca0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
bcb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
bcc0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
bcd0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
bce0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
bcf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
bd00: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
bd10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
bd20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
bd30: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
bd40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
bd50: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
bd60: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
bd70: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
bd80: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
bd90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
bda0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
bdb0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
bdc0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
bdd0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
bde0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
bdf0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
be00: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
be10: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
be20: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
be30: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
be40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
be50: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
be60: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
be70: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
be80: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
be90: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
bea0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
beb0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
bec0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
bed0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
bee0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
bef0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
bf00: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
bf10: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
bf20: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
bf30: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
bf40: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
bf50: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
bf60: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
bf70: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
bf80: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
bf90: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
bfa0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
bfb0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
bfc0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
bfd0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
bfe0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
bff0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
c000: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
c010: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
c020: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
c030: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
c040: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
c050: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
c060: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
c070: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
c080: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
c090: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
c0a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
c0b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
c0c0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
c0d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
c0e0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
c0f0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
c100: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
c110: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
c120: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
c130: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
c140: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
c150: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
c160: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
c170: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
c180: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
c190: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
c1a0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
c1b0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
c1c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
c1d0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
c1e0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
c1f0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
c200: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
c210: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
c220: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
c230: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
c240: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
c250: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
c260: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
c270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
c280: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
c290: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
c2a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
c2b0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
c2c0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
c2d0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
c2e0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
c2f0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
c300: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
c310: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
c320: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
c330: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
c340: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
c350: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
c360: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
c370: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
c380: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c t (*xShmMap)(sql
c390: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
c3a0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
c3b0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
c3c0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 e**);. int (*xS
c3d0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
c3e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
c3f0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
c400: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ags);. void (*x
c410: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
c420: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
c430: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 t (*xShmUnmap)(s
c440: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
c450: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
c460: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
c470: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
c480: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f version 2 */. /
c490: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
c4a0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
c4b0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
c4c0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
c4d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
c4e0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
c4f0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 l Opcodes.**.**
c500: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
c510: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
c520: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
c530: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
c540: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
c550: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
c560: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
c570: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
c580: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
c590: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
c5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
c5b0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
c5c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
c5d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
c5e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
c5f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
c600: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
c610: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
c620: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
c630: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
c640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
c650: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
c660: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
c670: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
c680: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
c690: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
c6a0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
c6b0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
c6c0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
c6d0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
c6e0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
c6f0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
c700: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
c710: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
c720: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
c730: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
c740: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
c750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
c760: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
c770: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 NT] opcode is us
c780: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 ed by SQLite to
c790: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 give the VFS.**
c7a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 layer a hint of
c7b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 how large the da
c7c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
c7d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 grow to be duri
c7e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e ng the.** curren
c7f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 t transaction.
c800: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 This hint is not
c810: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
c820: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 e accurate but i
c830: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c t.** is often cl
c840: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c ose. The underl
c850: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 ying VFS might c
c860: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f hoose to preallo
c870: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a cate database.**
c880: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 file space base
c890: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 d on this hint i
c8a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 n order to help
c8b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 writes to the da
c8c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 tabase.** file r
c8d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a un faster..**.**
c8e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
c8f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
c900: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
c910: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
c920: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
c930: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
c940: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
c950: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
c960: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
c970: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
c980: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
c990: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
c9a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
c9b0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
c9c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
c9d0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
c9e0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
c9f0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
ca00: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
ca10: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
ca20: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
ca30: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
ca40: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
ca50: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
ca60: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
ca70: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
ca80: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
ca90: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
caa0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
cab0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b ems..**.** The [
cac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
cad0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 E_POINTER] opcod
cae0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 e is used to obt
caf0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a ain a pointer.**
cb00: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
cb10: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 _file] object as
cb20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
cb30: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
cb40: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
cb50: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c n. See the [sql
cb60: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
cb70: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 l()] documentati
cb80: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 on for.** additi
cb90: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
cba0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 ..**.** ^(The [S
cbb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
cbc0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 _OMITTED] opcode
cbd0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e is generated in
cbe0: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 ternally by.** S
cbf0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 QLite and sent t
cc00: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 o all VFSes in p
cc10: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 lace of a call t
cc20: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 o the xSync meth
cc30: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 od.** when the d
cc40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
cc50: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 on has [PRAGMA s
cc60: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 ynchronous] set
cc70: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d to OFF.)^.** Som
cc80: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
cc90: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 Ses need this si
cca0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f gnal in order to
ccb0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 operate correct
ccc0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 ly.** when [PRAG
ccd0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
cce0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
ccf0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c ous=OFF] is set,
cd00: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 but most .** VF
cd10: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 Ses do not need
cd20: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 this signal and
cd30: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
cd40: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
cd50: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 de..** Applicati
cd60: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 ons should not c
cd70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c all [sqlite3_fil
cd80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
cd90: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 h this.** opcode
cda0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
cdb0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 disrupt the ope
cdc0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
cdd0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a ecialized VFSes.
cde0: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 ** that do requi
cdf0: 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 re it. .*/.#def
ce00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ce10: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 _LOCKSTATE
ce20: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
ce30: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_GET_LOCKPROXY
ce40: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 FILE 2.#def
ce50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
ce60: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
ce70: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
ce80: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 TE_LAST_ERRNO
ce90: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ceb0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
cec0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
ced0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
cee0: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 IZE 6.#def
cef0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
cf00: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 _FILE_POINTER
cf10: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
cf20: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d TE_FCNTL_SYNC_OM
cf30: 49 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a ITTED 8.../*
cf40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
cf50: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a tex Handle.**.**
cf60: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c The mutex modul
cf70: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 e within SQLite
cf80: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 defines [sqlite3
cf90: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e _mutex] to be an
cfa0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 .** abstract typ
cfb0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 e for a mutex ob
cfc0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 ject. The SQLit
cfd0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f e core never loo
cfe0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 ks.** at the int
cff0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
d000: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 tion of an [sqli
d010: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 te3_mutex]. It
d020: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 only.** deals wi
d030: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 th pointers to t
d040: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
d050: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a x] object..**.**
d060: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 Mutexes are cre
d070: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
d080: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
d090: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
d0a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 truct sqlite3_mu
d0b0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 tex sqlite3_mute
d0c0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 x;../*.** CAPI3R
d0d0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
d0e0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e Object.**.** An
d0f0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
d100: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
d110: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
d120: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
d130: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 n.** the SQLite
d140: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 core and the und
d150: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e erlying operatin
d160: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 g system. The "
d170: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e vfs".** in the n
d180: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 ame of the objec
d190: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 t stands for "vi
d1a0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
d1b0: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 m"..**.** The va
d1c0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 lue of the iVers
d1d0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 ion field is ini
d1e0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 tially 1 but may
d1f0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a be larger in.**
d200: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
d210: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 of SQLite. Add
d220: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d itional fields m
d230: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 ay be appended t
d240: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 o this.** object
d250: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 when the iVersi
d260: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 on value is incr
d270: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 eased. Note tha
d280: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a t the structure.
d290: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
d2a0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 3_vfs object cha
d2b0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e nges in the tran
d2c0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a saction between.
d2d0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
d2e0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e n 3.5.9 and 3.6.
d2f0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 0 and yet the iV
d300: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 ersion field was
d310: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 not.** modified
d320: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 ..**.** The szOs
d330: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 File field is th
d340: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 e size of the su
d350: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 bclassed [sqlite
d360: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 3_file].** struc
d370: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 ture used by thi
d380: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 s VFS. mxPathna
d390: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 me is the maximu
d3a0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 m length of.** a
d3b0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 pathname in thi
d3c0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 s VFS..**.** Reg
d3d0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f istered sqlite3_
d3e0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 vfs objects are
d3f0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 kept on a linked
d400: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a list formed by.
d410: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 ** the pNext poi
d420: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 nter. The [sqli
d430: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 te3_vfs_register
d440: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
d450: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 te3_vfs_unregist
d460: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 er()] interfaces
d470: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 manage this lis
d480: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 t.** in a thread
d490: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 -safe way. The
d4a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e [sqlite3_vfs_fin
d4b0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a d()] interface.*
d4c0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c * searches the l
d4d0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 ist. Neither th
d4e0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f e application co
d4f0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a de nor the VFS.*
d500: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
d510: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 should use the
d520: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a pNext pointer..*
d530: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 *.** The pNext f
d540: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 ield is the only
d550: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 field in the sq
d560: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 lite3_vfs.** str
d570: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 ucture that SQLi
d580: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 te will ever mod
d590: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c ify. SQLite wil
d5a0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a l only access.**
d5b0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
d5c0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 field while hold
d5d0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 ing a particular
d5e0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a static mutex..*
d5f0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
d600: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d n should never m
d610: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 odify anything w
d620: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ithin the sqlite
d630: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 3_vfs.** object
d640: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 once the object
d650: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 has been registe
d660: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a red..**.** The z
d670: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 Name field holds
d680: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
d690: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 VFS module. Th
d6a0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 e name must.** b
d6b0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 e unique across
d6c0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e all VFS modules.
d6d0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 .**.** ^SQLite g
d6e0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
d6f0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
d700: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a ameter to xOpen.
d710: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e ** is either a N
d720: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 ULL pointer or s
d730: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a tring obtained.*
d740: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 * from xFullPath
d750: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f name() with an o
d760: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 ptional suffix a
d770: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 dded..** ^If a s
d780: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 uffix is added t
d790: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 o the zFilename
d7a0: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 parameter, it wi
d7b0: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 ll.** consist of
d7c0: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 a single "-" ch
d7d0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 aracter followed
d7e0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e by no more than
d7f0: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 .** 10 alphanume
d800: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 ric and/or "-" c
d810: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 haracters..** ^S
d820: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 QLite further gu
d830: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a arantees that.**
d840: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c the string will
d850: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e be valid and un
d860: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 changed until xC
d870: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c lose() is.** cal
d880: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 led. Because of
d890: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
d8a0: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 tence,.** the [s
d8b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e qlite3_file] can
d8c0: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 safely store a
d8d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
d8e0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 * filename if it
d8f0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 needs to rememb
d900: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 er the filename
d910: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e for some reason.
d920: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 .** If the zFile
d930: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
d940: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c o xOpen is a NUL
d950: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 L pointer then x
d960: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 Open.** must inv
d970: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 ent its own temp
d980: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 orary name for t
d990: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 he file. ^Whene
d9a0: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c ver the .** xFil
d9b0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
d9c0: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 is NULL it will
d9d0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 also be the case
d9e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 that the.** fla
d9f0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c gs parameter wil
da00: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 l include [SQLIT
da10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
da20: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 LOSE]..**.** The
da30: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
da40: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 to xOpen() inclu
da50: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 des all bits set
da60: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 in.** the flags
da70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
da80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
da90: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 . Or if [sqlite
daa0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 3_open()].** or
dab0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
dac0: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e )] is used, then
dad0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 flags includes
dae0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c at least.** [SQL
daf0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
db00: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
db10: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 EN_CREATE]. .**
db20: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 If xOpen() opens
db30: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c a file read-onl
db40: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a y then it sets *
db50: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 pOutFlags to.**
db60: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
db70: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 OPEN_READONLY].
db80: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a Other bits in *
db90: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 pOutFlags may be
dba0: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 set..**.** ^(SQ
dbb0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 Lite will also a
dbc0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
dbd0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
dbe0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 the xOpen().**
dbf0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 call, depending
dc00: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 on the object be
dc10: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a ing opened:.**.*
dc20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
dc30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
dc40: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b N_DB].** <li> [
dc50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
dc60: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
dc70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
dc80: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e TEMP_DB].** <li>
dc90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
dca0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 EMP_JOURNAL].**
dcb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
dcc0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d EN_TRANSIENT_DB]
dcd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
dce0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
dcf0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
dd00: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
dd10: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
dd20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 [SQLITE_OPEN_W
dd30: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a AL].** </ul>)^.*
dd40: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f *.** The file I/
dd50: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e O implementation
dd60: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a can use the obj
dd70: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 ect type flags t
dd80: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 o.** change the
dd90: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 way it deals wit
dda0: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 h files. For ex
ddb0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
ddc0: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f ation.** that do
ddd0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 es not care abou
dde0: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 t crash recovery
ddf0: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 or rollback mig
de00: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f ht make.** the o
de10: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c pen of a journal
de20: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 file a no-op.
de30: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a Writes to this j
de40: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 ournal would.**
de50: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 also be no-ops,
de60: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 and any attempt
de70: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 to read the jour
de80: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e nal would return
de90: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 .** SQLITE_IOERR
dea0: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d . Or the implem
deb0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 entation might r
dec0: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 ecognize that a
ded0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
dee0: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 will be doing p
def0: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 age-aligned sect
df00: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 or reads and wri
df10: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a tes in a random.
df20: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 ** order and set
df30: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 up its I/O subs
df40: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c ystem accordingl
df50: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 y..**.** SQLite
df60: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f might also add o
df70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
df80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
df90: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a xOpen method:.*
dfa0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
dfb0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 > [SQLITE_OPEN_D
dfc0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
dfd0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
dfe0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a EN_EXCLUSIVE].**
dff0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
e000: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
e010: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 LETEONCLOSE] fla
e020: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 g means the file
e030: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 should be.** de
e040: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 leted when it is
e050: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b closed. ^The [
e060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
e070: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 TEONCLOSE].** wi
e080: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 ll be set for TE
e090: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 MP databases and
e0a0: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c their journals,
e0b0: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 transient.** da
e0c0: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 tabases, and sub
e0d0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 journals..**.**
e0e0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
e0f0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 N_EXCLUSIVE] fla
e100: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 g is always used
e110: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a in conjunction.
e120: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
e130: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
e140: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 flag, which are
e150: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a both directly.*
e160: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 * analogous to t
e170: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f he O_EXCL and O_
e180: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 CREAT flags of t
e190: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a he POSIX open().
e1a0: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c ** API. The SQL
e1b0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
e1c0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 VE flag, when pa
e1d0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ired with the .*
e1e0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 * SQLITE_OPEN_CR
e1f0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f EATE, is used to
e200: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 indicate that f
e210: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 ile should alway
e220: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c s.** be created,
e230: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 and that it is
e240: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 an error if it a
e250: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a lready exists..*
e260: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f * It is <i>not</
e270: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 i> used to indic
e280: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f ate the file sho
e290: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a uld be opened .*
e2a0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
e2b0: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 access..**.** ^A
e2c0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 t least szOsFile
e2d0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
e2e0: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 are allocated b
e2f0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 y SQLite.** to h
e300: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 old the [sqlite
e310: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 3_file] structur
e320: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
e330: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e third.** argumen
e340: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 t to xOpen. The
e350: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f xOpen method do
e360: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a es not have to.*
e370: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 * allocate the s
e380: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f tructure; it sho
e390: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 uld just fill it
e3a0: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a in. Note that.
e3b0: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 ** the xOpen met
e3c0: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 hod must set the
e3d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
e3e0: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 ethods to either
e3f0: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c .** a valid [sql
e400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
e410: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 object or to NU
e420: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 LL. xOpen must
e430: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 do.** this even
e440: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c if the open fail
e450: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 s. SQLite expec
e460: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 ts that the sqli
e470: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
e480: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c s.** element wil
e490: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 l be valid after
e4a0: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 xOpen returns r
e4b0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
e4c0: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 success.** or f
e4d0: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f ailure of the xO
e4e0: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 pen call..**.**
e4f0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d ^The flags argum
e500: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 ent to xAccess()
e510: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f may be [SQLITE_
e520: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a ACCESS_EXISTS].*
e530: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 * to test for th
e540: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 e existence of a
e550: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 file, or [SQLIT
e560: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
e570: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 TE] to.** test w
e580: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
e590: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
e5a0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 itable, or [SQLI
e5b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a TE_ACCESS_READ].
e5c0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 ** to test wheth
e5d0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 er a file is at
e5e0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 least readable.
e5f0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 The file can b
e600: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 e a.** directory
e610: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
e620: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
e630: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
e640: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
e650: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
e660: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
e670: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
e680: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
e690: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
e6a0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
e6b0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
e6c0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
e6d0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
e6e0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
e6f0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
e700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
e710: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
e720: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
e730: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
e740: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
e750: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
e760: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
e770: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
e780: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
e790: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
e7a0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
e7b0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
e7c0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
e7d0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
e7e0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 leep(), xCurrent
e7f0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 Time(), and xCur
e800: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a rentTimeInt64().
e810: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ** interfaces ar
e820: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 e not strictly a
e830: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c part of the fil
e840: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 esystem, but the
e850: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 y are.** include
e860: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 d in the VFS str
e870: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c ucture for compl
e880: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 eteness..** The
e890: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 xRandomness() fu
e8a0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 nction attempts
e8b0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 to return nBytes
e8c0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f bytes.** of goo
e8d0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d d-quality random
e8e0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 ness into zOut.
e8f0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
e900: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 e is.** the actu
e910: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 al number of byt
e920: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
e930: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 obtained..** Th
e940: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
e950: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c d causes the cal
e960: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 ling thread to s
e970: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c leep for at.** l
e980: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 east the number
e990: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 of microseconds
e9a0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 given. ^The xCu
e9b0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
e9c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
e9d0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
e9e0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
e9f0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 t date and time
ea00: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 as.** a floating
ea10: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a point value..**
ea20: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
ea30: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
ea40: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 returns, as an
ea50: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c integer, the Jul
ea60: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 ian.** Day Numbe
ea70: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 r multipled by 8
ea80: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
ea90: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
eaa0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
eab0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
eac0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
ead0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
eae0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
eaf0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
eb00: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
eb10: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
eb20: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
eb30: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
eb40: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
eb50: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
eb60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
eb70: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
eb80: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
eb90: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
eba0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
ebb0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
ebc0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
ebd0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
ebe0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
ebf0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
ec00: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
ec10: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
ec20: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
ec30: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
ec40: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
ec50: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
ec60: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
ec70: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
ec80: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
ec90: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
eca0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
ecb0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
ecc0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
ecd0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
ece0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
ecf0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
ed00: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
ed10: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
ed20: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
ed30: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
ed40: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
ed50: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
ed60: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
ed70: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
ed80: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
ed90: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
eda0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
edb0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
edc0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
edd0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
ede0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
edf0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
ee00: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
ee10: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
ee20: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
ee30: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
ee40: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
ee50: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
ee60: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
ee70: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
ee80: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
ee90: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
eea0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
eeb0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
eec0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
eed0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
eee0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
eef0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
ef00: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
ef10: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
ef20: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
ef30: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
ef40: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
ef50: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
ef60: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
ef70: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
ef80: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
ef90: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
efa0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
efb0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
efc0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
efd0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
efe0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
eff0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
f000: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
f010: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
f020: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
f030: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
f040: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
f050: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
f060: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
f070: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
f080: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
f090: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
f0a0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
f0b0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
f0c0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
f0d0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
f0e0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
f0f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
f100: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
f110: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
f120: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
f130: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
f140: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
f150: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
f160: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
f170: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
f180: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
f190: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
f1a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
f1b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
f1c0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
f1d0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
f1e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
f1f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
f200: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
f210: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
f220: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
f230: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
f240: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
f250: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
f260: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
f270: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
f280: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
f290: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
f2a0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
f2b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
f2c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
f2d0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
f2e0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
f2f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
f300: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
f310: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
f320: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
f330: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
f340: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
f350: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
f360: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
f370: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
f380: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
f390: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
f3a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
f3b0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
f3c0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
f3d0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
f3e0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
f3f0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
f400: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
f410: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
f420: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
f430: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
f440: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
f450: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
f460: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
f470: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
f480: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
f490: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
f4a0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
f4b0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
f4c0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
f4d0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
f4e0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
f4f0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
f500: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
f510: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
f520: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
f530: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
f540: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
f550: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
f560: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
f570: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
f580: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
f590: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
f5a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
f5b0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
f5c0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
f5d0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
f5e0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
f5f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
f600: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
f610: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
f620: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
f630: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
f640: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
f650: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
f660: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
f670: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
f680: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
f690: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
f6a0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
f6b0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
f6c0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
f6d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
f6e0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
f6f0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
f700: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
f710: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
f720: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
f730: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
f740: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
f750: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
f760: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
f770: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
f780: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
f790: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
f7a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
f7b0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
f7c0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
f7d0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
f7e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
f7f0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
f800: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
f810: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
f820: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
f830: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
f840: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
f850: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
f860: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
f870: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
f880: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
f890: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
f8a0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
f8b0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
f8c0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
f8d0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
f8e0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
f8f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
f900: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
f910: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
f920: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
f930: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
f940: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
f950: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
f960: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
f970: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
f980: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
f990: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
f9a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
f9b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
f9c0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
f9d0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
f9e0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
f9f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
fa00: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
fa10: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
fa20: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
fa30: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
fa40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
fa50: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
fa60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
fa70: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
fa80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
fa90: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
faa0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
fab0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
fac0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
fad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
fae0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
faf0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
fb00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
fb10: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
fb20: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
fb30: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
fb40: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
fb50: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
fb60: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
fb70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
fb80: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
fb90: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
fba0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
fbb0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
fbc0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
fbd0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
fbe0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
fbf0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
fc00: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
fc10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
fc20: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
fc30: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
fc40: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
fc50: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
fc60: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
fc70: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
fc80: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
fc90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
fca0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
fcb0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
fcc0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
fcd0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
fce0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
fcf0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
fd00: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
fd10: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
fd20: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
fd30: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 ven no the corre
fd40: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
fd50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
fd60: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
fd70: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
fd80: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
fd90: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
fda0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
fdb0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
fdc0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
fdd0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
fde0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
fdf0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
fe00: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
fe10: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
fe20: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
fe30: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
fe40: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
fe50: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
fe60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
fe70: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
fe80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
fe90: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
fea0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
feb0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
fec0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
fed0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
fee0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
fef0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
ff00: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
ff10: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
ff20: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
ff30: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
ff40: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
ff50: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
ff60: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
ff70: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
ff80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
ff90: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
ffa0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
ffb0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
ffc0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
ffd0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
ffe0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
fff0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
10000 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
10010 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
10020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
10030 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
10040 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
10050 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
10060 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
10070 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
10080 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
10090 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
100a0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
100b0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
100c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
100d0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
100e0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
100f0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
10100 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
10110 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
10120 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
10130 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
10140 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
10150 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
10160 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
10170 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
10180 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
10190 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
101a0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
101b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
101c0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
101d0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
101e0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
101f0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
10200 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
10210 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10220 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
10230 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
10240 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
10250 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
10260 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
10270 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
10280 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
10290 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
102a0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
102b0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
102c0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
102d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
102e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
102f0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
10300 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
10310 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
10320 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
10330 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
10340 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
10350 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
10360 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
10370 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
10380 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10390 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
103a0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
103b0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
103c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
103d0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
103e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
103f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
10400 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10410 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
10420 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
10430 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10440 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
10450 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
10460 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
10470 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
10480 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
10490 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
104a0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
104b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
104c0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
104d0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
104e0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
104f0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
10500 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
10510 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
10520 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
10530 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
10540 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
10550 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
10560 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
10570 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
10580 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
10590 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
105a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
105b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
105c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
105d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
105e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
105f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
10600 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
10610 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
10620 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10630 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
10640 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
10650 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
10660 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
10670 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
10680 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
10690 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
106a0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
106b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
106c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
106d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
106e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
106f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
10700 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
10710 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
10720 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
10730 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
10740 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
10750 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
10760 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
10770 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10780 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
10790 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
107a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
107b0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
107c0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
107d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
107e0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
107f0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
10800 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
10810 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
10820 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
10830 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
10840 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
10850 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
10860 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
10870 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
10880 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
10890 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
108a0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
108b0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
108c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
108d0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
108e0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
108f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10900 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
10910 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
10920 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
10930 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
10940 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
10950 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
10960 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
10970 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
10980 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
10990 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
109a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
109b0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
109c0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
109d0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
109e0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
109f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
10a00 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
10a10 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
10a20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
10a30 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
10a40 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
10a50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
10a60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
10a70 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
10a80 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
10a90 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
10aa0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
10ab0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
10ac0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
10ad0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
10ae0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
10af0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
10b00 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
10b10 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
10b20 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
10b30 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
10b40 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
10b50 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
10b60 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
10b70 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
10b80 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
10b90 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
10ba0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
10bb0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
10bc0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
10bd0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
10be0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
10bf0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
10c00 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
10c10 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
10c20 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
10c30 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
10c40 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
10c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
10c60 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
10c70 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
10c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
10c90 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
10ca0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
10cb0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
10cc0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
10cd0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
10ce0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
10cf0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
10d00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
10d10 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
10d20 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
10d30 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
10d40 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
10d50 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
10d60 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
10d70 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10d80 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
10d90 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
10da0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
10db0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
10dc0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
10dd0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
10de0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
10df0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
10e00 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
10e10 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
10e20 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
10e30 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
10e40 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
10e50 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
10e60 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
10e70 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
10e80 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
10e90 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
10ea0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
10eb0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
10ec0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
10ed0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
10ee0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
10ef0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
10f00 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
10f10 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
10f20 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
10f30 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
10f40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
10f50 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10f60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
10f70 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
10f80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
10f90 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
10fa0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
10fb0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
10fc0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 failure..*/.SQLI
10fd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
10fe0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f e3_initialize(vo
10ff0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
11000 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 int sqlite3_shut
11010 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 down(void);.SQLI
11020 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
11030 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 e3_os_init(void)
11040 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
11050 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
11060 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
11070 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
11080 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
11090 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 ibrary.**.** The
110a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
110b0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
110c0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 sed to make glob
110d0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e al configuration
110e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 .** changes to S
110f0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
11100 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f o tune SQLite to
11110 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
11120 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 eds of.** the ap
11130 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
11140 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
11150 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 ation is recomme
11160 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a nded for most.**
11170 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
11180 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e d so this routin
11190 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 e is usually not
111a0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 necessary. It
111b0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 is.** provided t
111c0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 o support rare a
111d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 pplications with
111e0 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a unusual needs..
111f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
11200 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
11210 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 face is not thre
11220 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 adsafe. The app
11230 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 lication.** must
11240 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 insure that no
11250 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
11260 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f erfaces are invo
11270 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 ked by other.**
11280 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 threads while sq
11290 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
112a0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 s running. Furt
112b0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 hermore, sqlite3
112c0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 _config().** may
112d0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
112e0 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
112f0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
11300 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
11310 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
11320 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
11330 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
11340 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
11350 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
11360 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
11370 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
11380 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
11390 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
113a0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
113b0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
113c0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
113d0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
113e0 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
113f0 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
11400 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
11410 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
11420 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
11430 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
11440 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
11450 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
11460 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
11470 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
11480 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
11490 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f er.** [SQLITE_CO
114a0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
114b0 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
114c0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
114d0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
114e0 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
114f0 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
11500 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
11510 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
11520 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
11530 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 g on the [SQLITE
11540 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
11550 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 READ | configura
11560 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 tion option].**
11570 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
11580 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 ument..**.** ^Wh
11590 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 en a configurati
115a0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 on option is set
115b0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
115c0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 () returns [SQLI
115d0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 TE_OK]..** ^If t
115e0 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b he option is unk
115f0 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 nown or SQLite i
11600 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 s unable to set
11610 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 the option.** th
11620 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
11630 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
11640 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e ro [error code].
11650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
11660 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 nt sqlite3_confi
11670 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a g(int, ...);../*
11680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
11690 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 nfigure database
116a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a connections.**.
116b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
116c0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
116d0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
116e0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
116f0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
11700 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
11710 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
11720 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
11730 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
11740 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
11750 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
11760 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
11770 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
11780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11790 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
117a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
117b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 )..**.** The sec
117c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
117d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
117e0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
117f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 he.** [SQLITE_DB
11800 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
11810 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
11820 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 verb] - an inte
11830 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 ger code .** tha
11840 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 t indicates what
11850 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
11860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11870 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
11880 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 nfigured..** Sub
11890 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
118a0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 s vary depending
118b0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 on the configur
118c0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a ation verb..**.*
118d0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
118e0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
118f0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
11900 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
11910 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
11920 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
11930 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sful..*/.SQLITE_
11940 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
11950 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
11960 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
11970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
11980 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
11990 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a tion Routines.**
119a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
119b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 of this object d
119c0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
119d0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c face between SQL
119e0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c ite.** and low-l
119f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
11a00 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
11a10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 .**.** This obje
11a20 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e ct is used in on
11a30 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 ly one place in
11a40 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
11a50 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 face..** A point
11a60 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
11a70 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
11a80 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
11a90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
11aa0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 config()] when t
11ab0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
11ac0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 option is.** [S
11ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
11ae0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f LOC] or [SQLITE_
11af0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
11b00 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 ]. .** By creat
11b10 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ing an instance
11b20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a of this object.*
11b30 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 * and passing it
11b40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
11b50 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
11b60 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 FIG_MALLOC]).**
11b70 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 during configura
11b80 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 tion, an applica
11b90 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 tion can specify
11ba0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
11bb0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
11bc0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 tion subsystem f
11bd0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 or SQLite to use
11be0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a for all of its.
11bf0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ** dynamic memor
11c00 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e y needs..**.** N
11c10 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ote that SQLite
11c20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 comes with sever
11c30 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d al [built-in mem
11c40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a ory allocators].
11c50 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 ** that are perf
11c60 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
11c70 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
11c80 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
11c90 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
11ca0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
11cb0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
11cc0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
11cd0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
11ce0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
11cf0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
11d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
11d10 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
11d20 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
11d30 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
11d40 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
11d50 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
11d60 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
11d70 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
11d80 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
11d90 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
11da0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
11db0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
11dc0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
11dd0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
11de0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
11df0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
11e00 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
11e10 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 xMalloc and xFre
11e20 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
11e30 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
11e40 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
11e50 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 e() functions fr
11e60 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
11e70 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 C library..** Th
11e80 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f e xRealloc metho
11e90 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 d must work like
11ea0 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 realloc() from
11eb0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
11ec0 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 ibrary.** with t
11ed0 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 he exception tha
11ee0 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 t if the second
11ef0 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 argument to xRea
11f00 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a lloc is zero,.**
11f10 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 xRealloc must b
11f20 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d e a no-op - it m
11f30 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 ust not perform
11f40 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f any allocation o
11f50 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f r.** deallocatio
11f60 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 n. ^SQLite guar
11f70 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
11f80 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
11f90 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 to.** xRealloc i
11fa0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 s always a value
11fb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 returned by a p
11fc0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f rior call to xRo
11fd0 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f undup..** And so
11fe0 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 in cases where
11ff0 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 xRoundup always
12000 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 returns a positi
12010 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 ve number,.** xR
12020 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f ealloc can perfo
12030 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 rm exactly as th
12040 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 e standard libra
12050 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ry realloc() and
12060 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 .** still be in
12070 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 compliance with
12080 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69 this specificati
12090 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 on..**.** xSize
120a0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
120b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
120c0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
120d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
120e0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
120f0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
12100 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
12110 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
12120 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
12130 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
12140 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
12150 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
12160 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
12170 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
12180 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
12190 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
121a0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
121b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
121c0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
121d0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
121e0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
121f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
12200 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
12210 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
12220 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
12230 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
12240 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
12250 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
12260 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
12270 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
12280 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
12290 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
122a0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
122b0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
122c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
122d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
122e0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
122f0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
12300 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
12310 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
12320 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
12330 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
12340 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
12350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
12360 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
12370 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
12380 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
12390 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
123a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
123b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
123c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
123d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
123e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
123f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
12400 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
12410 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
12420 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
12430 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
12440 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
12450 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
12460 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
12470 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
12480 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
12490 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
124a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
124b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
124c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
124d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
124e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
124f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
12500 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
12510 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
12520 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
12530 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
12540 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
12550 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
12560 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
12570 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
12580 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
12590 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
125a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
125b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
125c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
125d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
125e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
125f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
12600 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
12610 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
12620 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
12630 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
12640 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
12650 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
12660 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
12670 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
12680 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
12690 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
126a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
126b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
126c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
126d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
126e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
126f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
12700 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
12710 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
12720 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
12730 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
12740 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
12750 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
12760 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
12770 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
12780 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
12790 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
127a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
127b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
127c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
127d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
127e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
127f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
12800 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
12810 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
12820 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
12830 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
12840 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
12850 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
12860 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
12870 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
12880 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
12890 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
128a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
128b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
128c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
128d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
128e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
128f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
12900 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
12910 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
12920 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
12930 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
12940 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
12950 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
12960 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
12970 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
12980 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
12990 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
129a0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
129b0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
129c0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
129d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
129e0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
129f0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
12a00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
12a10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
12a20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
12a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12a40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
12a50 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ptions.**.** The
12a60 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
12a70 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
12a80 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
12a90 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
12aa0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
12ab0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
12ac0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
12ad0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12ae0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
12af0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
12b00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
12b10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
12b20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
12b30 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
12b40 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
12b50 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
12b60 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
12b70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
12b80 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
12b90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
12ba0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
12bb0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
12bc0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
12bd0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
12be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
12bf0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
12c00 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
12c10 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
12c20 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
12c30 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
12c40 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
12c50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
12c60 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
12c70 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
12c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
12c90 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
12ca0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
12cb0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
12cc0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
12cd0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
12ce0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
12cf0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
12d00 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
12d10 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
12d20 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
12d30 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
12d40 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
12d50 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
12d60 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
12d70 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
12d80 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
12d90 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
12da0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
12db0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
12dc0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
12dd0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
12de0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
12df0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
12e00 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
12e10 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
12e20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
12e30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
12e40 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
12e50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
12e60 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
12e70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
12e80 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
12e90 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
12ea0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
12eb0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
12ec0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
12ed0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
12ee0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
12ef0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
12f00 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
12f10 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
12f20 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
12f30 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
12f40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
12f50 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 ] to Multi-threa
12f60 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
12f70 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
12f80 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b ** mutexing on [
12f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12fa0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
12fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
12fc0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 jects..** The ap
12fd0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 plication is res
12fe0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 ponsible for ser
12ff0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 ializing access
13000 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 to.** [database
13010 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
13020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
13030 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 ments]. But oth
13040 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 er mutexes.** ar
13050 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 e enabled so tha
13060 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 t SQLite will be
13070 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 safe to use in
13080 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
13090 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 .** environment
130a0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 as long as no tw
130b0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 o threads attemp
130c0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d t to use the sam
130d0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
130e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 onnection] at th
130f0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 e same time. ^I
13100 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
13110 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
13120 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
13130 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
13140 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
13150 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
13160 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
13170 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
13180 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 the Multi-threa
13190 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
131a0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
131b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
131c0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
131d0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
131e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
131f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
13200 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 ITHREAD configur
13210 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
13220 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
13240 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 LIZED</dt>.** <d
13250 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
13260 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
13270 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
13280 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
13290 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
132a0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 de] to Serialize
132b0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 d. In other word
132c0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 s, this option e
132d0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 nables.** all mu
132e0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 texes including
132f0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a the recursive.**
13300 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 mutexes on [dat
13310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13320 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
13330 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
13340 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d ts..** In this m
13350 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 ode (which is th
13360 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 e default when S
13370 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13380 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 d with.** [SQLIT
13390 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 E_THREADSAFE=1])
133a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
133b0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 ary will itself
133c0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 serialize access
133d0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 .** to [database
133e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
133f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
13400 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 ements] so that
13410 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 the.** applicati
13420 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 on is free to us
13430 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 e the same [data
13440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
13450 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 or the.** same
13460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
13470 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e ent] in differen
13480 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 t threads at the
13490 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e same time..** ^
134a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
134b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
134c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
134d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
134e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
134f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
13500 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
13510 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
13520 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 t the Serialized
13530 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
13540 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
13550 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
13560 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
13570 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
13580 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
13590 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
135a0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 LIZED configurat
135b0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
135c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
135d0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
135e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
135f0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
13600 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
13610 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
13620 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
13630 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
13640 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13650 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
13660 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
13670 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
13680 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
13690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
136a0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
136b0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
136c0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
136d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
136e0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
136f0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
13700 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
13710 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
13720 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
13730 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
13740 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
13750 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
13760 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
13770 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
13780 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
13790 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
137a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e G_GETMALLOC</dt>
137b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
137c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
137d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
137e0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
137f0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
13800 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
13810 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
13820 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
13830 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
13840 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
13850 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
13860 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
13870 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
13880 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
13890 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
138a0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
138b0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
138c0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
138e0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
138f0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
13900 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
13910 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
13920 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
13930 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
13940 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
13950 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
13960 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
13970 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
13980 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13990 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
139a0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
139b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
139c0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
139d0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
139e0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
139f0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
13a00 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
13a10 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 tatistics. ^(Whe
13a20 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
13a30 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
13a40 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 re disabled, the
13a50 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 .** following S
13a60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
13a70 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
13a80 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
13a90 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
13aa0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
13ab0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
13ac0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
13ad0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
13ae0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
13af0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
13b00 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
13b10 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
13b20 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
13b30 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
13b40 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
13b50 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
13b60 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
13b70 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
13b80 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
13b90 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
13ba0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
13bb0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
13bc0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
13bd0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
13be0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
13bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
13c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
13c10 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
13c20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 > ^This option s
13c30 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
13c40 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
13c50 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
13c60 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 use for.** scrat
13c70 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 ch memory. Ther
13c80 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
13c90 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 ments: A pointe
13ca0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
13cb0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
13cc0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
13cd0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f the scratch allo
13ce0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a cations will be.
13cf0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 ** drawn, the si
13d00 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 ze of each scrat
13d10 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 ch allocation (s
13d20 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d z),.** and the m
13d30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
13d40 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
13d50 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 ions (N). The s
13d60 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 z.** argument mu
13d70 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 st be a multiple
13d80 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 of 16..** The f
13d90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
13da0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 st be a pointer
13db0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 to an 8-byte ali
13dc0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f gned buffer.** o
13dd0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
13de0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
13df0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
13e00 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
13e10 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 n two scratch bu
13e20 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 ffers per thread
13e30 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c . So.** N shoul
13e40 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 d be set to twic
13e50 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d e the expected m
13e60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
13e70 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 threads..** ^SQ
13e80 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
13e90 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 require a scratc
13ea0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
13eb0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
13ec0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
13ed0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 se page size. ^I
13ee0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e f SQLite needs n
13ef0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a eeds additional.
13f00 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
13f10 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 y beyond what is
13f20 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
13f30 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
13f40 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a option, then .**
13f50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13f60 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 ()] will be used
13f70 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d to obtain the m
13f80 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 emory needed.</d
13f90 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
13fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
13fb0 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ACHE</dt>.** <dd
13fc0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 > ^This option s
13fd0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
13fe0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
13ff0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
14000 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 use for.** the d
14010 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 atabase page cac
14020 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 he with the defa
14030 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 ult page cache i
14040 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a mplemenation. .
14050 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
14060 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
14070 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
14080 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
14090 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
140a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
140b0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
140c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
140d0 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a _PCACHE option..
140e0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
140f0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
14100 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 this option: A p
14110 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 ointer to 8-byte
14120 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f aligned.** memo
14130 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ry, the size of
14140 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 each page buffer
14150 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e (sz), and the n
14160 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 umber of pages (
14170 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
14180 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
14190 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
141a0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
141b0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 e page.** (a pow
141c0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 er of two betwee
141d0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 n 512 and 32768)
141e0 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 plus a little e
141f0 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a xtra for each.**
14200 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e page header. ^
14210 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 The page header
14220 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 size is 20 to 40
14230 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 bytes depending
14240 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 on.** the host
14250 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e architecture. ^
14260 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
14270 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
14280 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
14290 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 to make sz a li
142a0 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 ttle too large.
142b0 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
142c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
142d0 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 int to an alloca
142e0 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 tion of at least
142f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
14300 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
14310 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d e will use the m
14320 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 emory provided b
14330 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
14340 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 ment to satisfy
14350 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 its.** memory ne
14360 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 eds for the firs
14370 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 t N pages that i
14380 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e t adds to cache.
14390 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c ^If additional
143a0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
143b0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
143c0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
143d0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
143e0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 option, then.**
143f0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b SQLite goes to [
14400 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14410 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 ] for the additi
14420 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 onal storage spa
14430 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 ce..** The point
14440 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
14450 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a argument must.**
14460 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
14470 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
14480 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
14490 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
144a0 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e te.** will be un
144b0 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
144c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
144d0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
144e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
144f0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
14500 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
14510 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
14520 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f e will use.** fo
14530 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
14540 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f amic memory allo
14550 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 cation needs bey
14560 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 ond those provid
14570 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 ed.** for by [SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
14590 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 TCH] and [SQLITE
145a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
145b0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 E]..** There are
145c0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
145d0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 : An 8-byte alig
145e0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ned pointer to t
145f0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 he memory,.** th
14600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
14610 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 s in the memory
14620 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 buffer, and the
14630 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
14640 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 on size..** ^If
14650 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 the first pointe
14660 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
14670 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 inter) is NULL,
14680 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 then SQLite reve
14690 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 rts.** to using
146a0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f its default memo
146b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 ry allocator (th
146c0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
146d0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e ) implementation
146e0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e ),.** undoing an
146f0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 y prior invocati
14700 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f on of [SQLITE_CO
14710 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e NFIG_MALLOC]. ^
14720 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
14730 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
14740 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 NULL and either
14750 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
14760 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 EMSYS3] or.** [S
14770 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
14780 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 SYS5] are define
14790 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 d, then the alte
147a0 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
147b0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
147c0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
147d0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
147e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
147f0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
14800 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
14810 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
14820 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
14830 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
14840 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
14850 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
14860 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
14870 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a l be undefined..
14880 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 ** The minimum a
14890 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 llocation size i
148a0 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31 32 s capped at 2^12
148b0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c . Reasonable val
148c0 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d ues.** for the m
148d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
148e0 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74 n size are 2^5 t
148f0 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e hrough 2^8.</dd>
14900 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
14910 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
14920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14930 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
14940 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
14950 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
14960 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
14970 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
14980 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
14990 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
149a0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
149b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
149c0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
149d0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 l mutex routines
149e0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
149f0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 lace.** the mute
14a00 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 x routines built
14a10 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
14a20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
14a30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
14a40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
14a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
14a60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
14a70 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c before the call
14a80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
14a90 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e config()] return
14aa0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 s. ^If SQLite is
14ab0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
14ac0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
14ad0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
14ae0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
14b00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
14b10 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
14b20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
14b30 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
14b40 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
14b50 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
14b60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
14b70 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
14b80 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 FIG_MUTEX config
14b90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
14ba0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
14bb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
14bc0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
14bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14be0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
14bf0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
14c00 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
14c10 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
14c20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
14c30 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
14c40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
14c50 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
14c60 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
14c70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
14c80 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
14c90 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
14ca0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
14cb0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
14cc0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
14cd0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
14ce0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
14cf0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 the default mut
14d00 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ex allocation.**
14d10 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
14d20 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f wrapper used to
14d30 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 track mutex usa
14d40 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e ge for performan
14d50 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 ce.** profiling
14d60 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 or testing, for
14d70 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 example. ^If S
14d80 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
14d90 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
14da0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
14db0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
14dc0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
14dd0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
14de0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d .** the entire m
14df0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 utexing subsyste
14e00 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f m is omitted fro
14e10 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 m the build and
14e20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a hence calls to.*
14e30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
14e40 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 g()] with the SQ
14e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
14e60 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
14e70 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
14e80 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
14e90 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
14ea0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
14eb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
14ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
14ed0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
14ee0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
14ef0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
14f00 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
14f10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
14f20 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
14f30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
14f40 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
14f50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14f60 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
14f70 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
14f80 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
14f90 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
14fa0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
14fb0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
14fc0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
14fd0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
14fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14ff0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
15000 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
15010 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
15020 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
15030 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
15040 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
15050 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
15060 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
15070 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
15080 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
15090 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
150a0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
150b0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
150c0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
150d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
150e0 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a G_PCACHE</dt>.**
150f0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
15100 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
15110 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
15120 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
15130 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 o.** an [sqlite3
15140 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d _pcache_methods]
15150 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
15160 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 bject specifies
15170 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
15180 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 to a custom pag
15190 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
151a0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 tation.)^ ^SQLi
151b0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
151c0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 of the.** object
151d0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 and uses it for
151e0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
151f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c ry allocations.<
15200 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
15210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15220 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c PCACHE</dt>.** <
15230 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
15240 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
15250 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
15260 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
15270 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 an.** [sqlite3_p
15280 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
15290 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
152a0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
152b0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
152c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
152d0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
152e0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ct.)^ </dd>.**.*
152f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
15300 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 FIG_LOG</dt>.**
15310 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
15320 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
15330 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
15340 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
15350 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
15360 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
15370 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
15380 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
15390 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
153a0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
153b0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
153c0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
153d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
153e0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
153f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
15400 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
15410 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
15420 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
15430 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
15440 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
15450 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
15460 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
15470 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
15480 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
15490 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
154a0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
154b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
154c0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
154d0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
154e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
154f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
15500 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
15510 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
15520 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
15530 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
15540 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
15550 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
15560 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
15570 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
15580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
15590 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
155a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
155b0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
155c0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
155d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
155e0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
155f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
15600 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
15610 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
15620 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
15630 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
15640 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
15650 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
15660 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
15670 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
15680 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
15690 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
156a0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
156b0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
156c0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
156d0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
156e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
156f0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
15700 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
15710 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
15720 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
15730 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
15740 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
15750 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
15760 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
15770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
15780 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
15790 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
157a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
157b0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
157c0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
157d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
157e0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
157f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
15800 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15810 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
15820 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
15830 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
15840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
15850 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
15860 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
15870 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
15880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15890 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
158a0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
158b0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
158c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
158d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
158e0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
158f0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
15900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
15920 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
15930 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
15940 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
15950 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15960 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
15970 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
15980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15990 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
159a0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
159b0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
159c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
159d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
159e0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
159f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
15a00 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
15a10 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
15a20 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
15a30 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
15a40 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
15a50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15a60 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
15a70 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
15a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15a90 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
15aa0 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 14 /* sqlite
15ab0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
15ac0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
15ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
15ae0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 ACHE 15 /* s
15af0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
15b00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
15b10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15b20 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 LOG 16
15b30 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a /* xFunc, void*
15b40 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
15b50 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
15b60 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 nnection Configu
15b70 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
15b80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
15b90 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
15ba0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
15bb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
15bc0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
15bd0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
15be0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
15bf0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
15c00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
15c10 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
15c20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
15c30 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
15c40 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
15c50 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
15c60 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
15c70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15c80 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
15c90 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
15ca0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
15cb0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
15cc0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
15cd0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
15ce0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
15cf0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
15d00 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 call worked. ^T
15d10 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
15d20 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
15d30 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
15d40 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
15d50 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
15d60 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
15d70 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
15d80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
15d90 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
15da0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
15db0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
15dc0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
15dd0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
15de0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
15df0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
15e00 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
15e10 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
15e20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
15e30 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
15e40 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
15e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
15e60 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 tion]..** ^The f
15e70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
15e80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
15e90 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
15ea0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
15eb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
15ec0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
15ed0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
15ee0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ide memory..** ^
15ef0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15f00 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c nt after the SQL
15f10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
15f20 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d KASIDE verb.** m
15f30 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 ay be NULL in wh
15f40 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
15f50 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 will allocate th
15f60 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 e.** lookaside b
15f70 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 uffer itself usi
15f80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
15f90 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f oc()]. ^The seco
15fa0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
15fb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
15fc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
15fd0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 fer slot. ^The
15fe0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
15ff0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
16000 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
16010 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
16020 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
16030 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
16040 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
16050 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
16060 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
16070 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
16080 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 arguments. The
16090 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 buffer.** must b
160a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
160b0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8-byte boundary.
160c0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ^If the second
160d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
160e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
160f0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 LOOKASIDE is not
16100 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 a multiple of 8
16110 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c , it is internal
16120 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f ly.** rounded do
16130 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 wn to the next s
16140 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 maller multiple
16150 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f of 8. ^(The loo
16160 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a kaside memory.**
16170 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
16180 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
16190 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c nnection can onl
161a0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 y be changed whe
161b0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 n that.** connec
161c0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 tion is not curr
161d0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b ently using look
161e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 aside memory, or
161f0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a in other words.
16200 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 ** when the "cur
16210 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 rent value" retu
16220 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
16230 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 te3_db_status](D
16240 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ,[SQLITE_CONFIG_
16250 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
16260 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 is zero..** Any
16270 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 attempt to chang
16280 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 e the lookaside
16290 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 memory configura
162a0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 tion when lookas
162b0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 ide.** memory is
162c0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 in use leaves t
162d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
162e0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 unchanged and r
162f0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 eturns .** [SQLI
16300 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e TE_BUSY].)^</dd>
16310 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
16320 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
16330 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c E_FKEY</dt>.** <
16340 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
16350 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
16360 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
16370 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 e enforcement of
16380 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
16390 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 constraints].
163a0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
163b0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
163c0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
163d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
163e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
163f0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
16400 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
16410 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 nt,.** positive
16420 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 to enable FK enf
16430 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 orcement or nega
16440 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b tive to leave FK
16450 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 enforcement.**
16460 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
16470 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
16480 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
16490 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
164a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
164b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
164c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
164d0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 FK enforcement i
164e0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 s off or on.** f
164f0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
16500 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
16510 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
16520 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
16530 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
16540 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 e the FK enforce
16550 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 ment setting is
16560 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
16570 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
16580 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
16590 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
165a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
165b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
165c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
165d0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
165e0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
165f0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
16600 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
16610 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
16620 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
16630 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
16640 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
16650 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
16660 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
16670 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
16680 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
16690 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
166a0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
166b0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
166c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
166d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
166e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
166f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
16700 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
16710 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
16720 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
16730 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
16740 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
16750 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
16760 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
16770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
16780 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
16790 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
167a0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
167b0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
167c0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
167d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
167e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
167f0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 1001 /*
16800 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
16810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16820 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
16830 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f FKEY 1002 /
16840 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
16850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
16860 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
16870 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 GGER 1003 /* i
16880 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a nt int* */.../*.
16890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
168a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
168b0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
168c0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 odes.**.** ^The
168d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
168e0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
168f0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
16900 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
16910 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
16920 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
16930 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
16940 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
16950 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
16960 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
16970 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
16980 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
16990 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
169a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
169b0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
169c0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
169d0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
169e0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
169f0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
16a00 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
16a10 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
16a20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
16a30 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
16a40 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
16a50 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
16a60 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
16a70 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
16a80 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
16a90 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
16aa0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
16ab0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
16ac0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
16ad0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
16ae0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
16af0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
16b00 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
16b10 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
16b20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
16b30 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
16b40 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
16b50 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
16b60 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
16b70 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
16b80 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
16b90 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
16ba0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
16bb0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
16bc0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
16bd0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
16be0 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
16bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
16c00 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
16c10 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 gument. ^If no
16c20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
16c30 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 RT]s.** have eve
16c40 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
16c50 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e at database conn
16c60 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 ection, zero is
16c70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
16c80 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
16c90 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
16ca0 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
16cb0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
16cc0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
16cd0 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
16ce0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
16cf0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
16d00 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e gger is running.
16d10 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
16d20 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 trigger termina
16d30 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 tes, the value r
16d40 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
16d50 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 routine.** rever
16d60 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 ts to the last v
16d70 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 alue inserted be
16d80 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
16d90 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 fired.)^.**.**
16da0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
16db0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
16dc0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
16dd0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
16de0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
16df0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
16e00 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
16e10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
16e20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
16e30 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
16e40 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
16e50 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
16e60 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
16e70 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
16e80 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
16e90 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
16ea0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
16eb0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
16ec0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
16ed0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
16ee0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
16ef0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
16f00 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
16f10 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
16f20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
16f30 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
16f40 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
16f50 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
16f60 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
16f70 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
16f80 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
16f90 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
16fa0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
16fb0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
16fc0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
16fd0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
16fe0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
16ff0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
17000 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
17010 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
17020 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
17030 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
17040 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
17050 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
17060 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
17070 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
17080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
17090 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
170a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
170b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
170c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
170d0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
170e0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
170f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
17100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17110 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
17120 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17130 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
17140 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
17150 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
17160 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
17170 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
17180 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
17190 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
171a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
171b0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
171c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
171d0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
171e0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
171f0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
17200 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
17210 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
17220 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
17230 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17240 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
17250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
17260 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
17270 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
17280 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
17290 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
172a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
172b0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
172c0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
172d0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
172e0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
172f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
17300 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
17310 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
17320 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
17330 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
17340 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
17350 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 parameter..** ^(
17360 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
17370 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
17380 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
17390 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
173a0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
173b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
173c0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
173d0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
173e0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
173f0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b rs or [foreign k
17400 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
17410 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 not counted.)^ U
17420 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 se the.** [sqlit
17430 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
17440 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ()] function to
17450 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
17460 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
17470 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 .** including ch
17480 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
17490 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 triggers and for
174a0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
174b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 ..**.** ^Changes
174c0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
174d0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 are simulated by
174e0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
174f0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 trigger].** are
17500 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e not counted. On
17510 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 ly real table ch
17520 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
17530 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f d..**.** ^(A "ro
17540 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
17550 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
17560 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
17570 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
17580 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
17590 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
175a0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
175b0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
175c0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
175d0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 ffects of [REPLA
175e0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
175f0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
17600 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
17610 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 ocessing, [DROP
17620 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e TABLE], or by an
17630 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 y other.** mecha
17640 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 nisms do not cou
17650 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 nt as direct row
17660 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a changes.)^.**.*
17670 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
17680 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
17690 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
176a0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
176b0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
176c0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 cript of a [CREA
176d0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
176e0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 gger]. .** Most
176f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
17700 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
17710 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
17720 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
17730 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
17740 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
17750 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
17760 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
17770 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
17780 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
17790 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
177a0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
177b0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
177c0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
177d0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
177e0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
177f0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
17800 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 .** ^Calling [sq
17810 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
17820 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
17830 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
17840 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
17850 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
17860 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ontext..**.** ^T
17870 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
17880 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
17890 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 of direct row ch
178a0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 anges in the.**
178b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
178c0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
178d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
178e0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a within the same.
178f0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
17900 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c xt..**.** ^Thus,
17910 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
17920 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
17930 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
17940 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
17950 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
17960 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
17970 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
17980 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
17990 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
179a0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
179b0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 vel. ^(Within t
179c0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 he body of a tri
179d0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c gger,.** the sql
179e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 ite3_changes() i
179f0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
17a00 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 called to find t
17a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
17a20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
17a30 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
17a40 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
17a50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
17a60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 .** statement wi
17a70 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
17a80 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
17a90 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 r..** However, t
17aa0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e he number return
17ab0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
17ac0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 ude changes.** c
17ad0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 aused by subtrig
17ae0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 gers since those
17af0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 have their own
17b00 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a context.)^.**.**
17b10 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
17b20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
17b30 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
17b40 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
17b50 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
17b60 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
17b70 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
17b80 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
17b90 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
17ba0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
17bb0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
17bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
17bd0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
17be0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
17bf0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
17c00 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
17c10 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
17c20 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
17c30 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
17c40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
17c50 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
17c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
17c70 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
17c80 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
17c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
17ca0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
17cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 e number of row
17cc0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
17cd0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b y [INSERT],.** [
17ce0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 UPDATE] or [DELE
17cf0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 TE] statements s
17d00 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 ince the [databa
17d10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
17d20 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 as opened..** ^(
17d30 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e The count return
17d40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f ed by sqlite3_to
17d50 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e tal_changes() in
17d60 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 cludes all chang
17d70 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b es.** from all [
17d80 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
17d90 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 trigger] contex
17da0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d ts and changes m
17db0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 ade by.** [forei
17dc0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e gn key actions].
17dd0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
17de0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
17df0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
17e00 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
17e10 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 t [REPLACE] cons
17e20 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 traints,.** do r
17e30 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 ollbacks or ABOR
17e40 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 T processing, or
17e50 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 [DROP TABLE] pr
17e60 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a ocessing. The.*
17e70 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 * count does not
17e80 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 include rows of
17e90 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 views that fire
17ea0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
17eb0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f trigger],.** tho
17ec0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 ugh if the INSTE
17ed0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 AD OF trigger ma
17ee0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 kes changes of i
17ef0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 ts own, those ch
17f00 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f anges .** are co
17f10 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 unted.)^.** ^The
17f20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
17f30 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f hanges() functio
17f40 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 n counts the cha
17f50 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a nges as soon as.
17f60 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
17f70 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
17f80 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 is completed (w
17f90 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
17fa0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 t handle.** is p
17fb0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
17fc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
17fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
17fe0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 )])..**.** See a
17ff0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
18000 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
18010 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
18020 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
18030 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 gma], and the [t
18040 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 otal_changes() S
18050 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
18060 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
18070 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
18080 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
18090 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
180a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
180b0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
180c0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
180d0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
180e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
180f0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
18100 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
18110 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
18120 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
18130 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
18140 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
18150 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
18160 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
18170 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 g Query.**.** ^T
18180 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
18190 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
181a0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
181b0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
181c0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
181d0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
181e0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
181f0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
18200 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
18210 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
18220 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
18230 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
18240 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
18250 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
18260 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
18270 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
18280 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
18290 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
182a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
182b0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
182c0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
182d0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
182e0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
182f0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
18300 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
18310 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
18320 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
18330 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
18340 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
18350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
18360 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
18370 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
18380 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
18390 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
183a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
183b0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
183c0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
183d0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
183e0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
183f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
18400 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
18410 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
18420 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
18430 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
18440 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
18450 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
18460 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
18470 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
18480 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
18490 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
184a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
184b0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
184c0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
184d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
184e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
184f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
18500 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
18510 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
18520 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
18530 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
18540 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
18550 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
18560 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
18570 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18580 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
18590 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
185a0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
185b0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
185c0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
185d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
185e0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
185f0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
18600 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
18610 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
18620 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
18630 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
18640 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
18650 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
18660 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
18670 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
18680 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
18690 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
186a0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
186b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
186c0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
186d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
186e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
186f0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
18700 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
18710 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
18720 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
18730 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
18740 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
18750 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
18760 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
18770 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
18780 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
18790 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
187a0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
187b0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
187c0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
187d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
187e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
187f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
18800 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
18810 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
18820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
18830 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
18840 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
18850 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
18860 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
18870 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
18880 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 ely happen..*/.S
18890 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
188a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
188b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
188c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
188d0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
188e0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
188f0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
18900 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
18910 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
18920 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
18930 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
18940 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
18950 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
18960 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
18970 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
18980 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
18990 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
189a0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
189b0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
189c0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
189d0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
189e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
189f0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
18a00 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
18a10 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
18a20 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
18a30 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
18a40 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
18a50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
18a60 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
18a70 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
18a80 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
18a90 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
18aa0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
18ab0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
18ac0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
18ad0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
18ae0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
18af0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
18b00 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
18b10 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
18b20 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
18b30 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
18b40 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
18b50 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
18b60 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
18b70 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
18b80 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
18b90 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
18ba0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
18bb0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
18bc0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
18bd0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
18be0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
18bf0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
18c00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
18c10 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
18c20 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
18c30 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
18c40 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
18c50 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
18c60 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
18c70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
18c80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
18c90 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
18ca0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
18cb0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
18cc0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
18cd0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
18ce0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
18cf0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
18d00 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
18d10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
18d20 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
18d30 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
18d40 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
18d50 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
18d60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
18d70 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
18d80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
18d90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
18da0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
18db0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
18dc0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
18dd0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
18de0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
18df0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
18e00 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
18e10 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
18e20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
18e30 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
18e40 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
18e50 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
18e60 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
18e70 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
18e80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
18e90 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
18ea0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
18eb0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
18ec0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
18ed0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
18ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
18ef0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
18f00 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 der..*/.SQLITE_A
18f10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
18f20 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
18f30 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 ar *sql);.SQLITE
18f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
18f50 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
18f60 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
18f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
18f80 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
18f90 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
18fa0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
18fb0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
18fc0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
18fd0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
18fe0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
18ff0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
19000 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
19010 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
19020 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
19030 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
19040 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
19050 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
19060 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
19070 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
19080 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
19090 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
190a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
190b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
190c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
190d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
190e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
190f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
19100 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
19110 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
19120 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
19130 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
19140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
19150 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
19160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
19170 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
19180 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
19190 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
191a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
191b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
191c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
191d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
191e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
191f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
19200 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
19210 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
19220 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
19230 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
19240 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
19250 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
19260 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
19270 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
19280 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
19290 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
192a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
192b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
192c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
192d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
192e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
192f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
19300 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
19310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
19320 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
19330 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
19340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
19350 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
19360 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
19370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
19380 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
19390 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
193a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
193b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
193c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
193d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
193e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
193f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
19400 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
19410 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
19420 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
19430 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
19440 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
19450 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
19460 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
19470 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
19480 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
19490 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
194a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
194b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
194c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
194d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
194e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
194f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
19500 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
19510 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
19520 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
19530 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
19540 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
19550 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
19560 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
19570 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
19580 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
19590 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
195a0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
195b0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
195c0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
195d0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
195e0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
195f0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
19600 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
19610 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
19620 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
19630 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
19640 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
19650 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
19660 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
19670 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
19680 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
19690 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
196a0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
196b0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
196c0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
196d0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
196e0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
196f0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
19700 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
19710 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
19720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
19730 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
19740 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
19750 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
19760 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
19770 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
19780 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
19790 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
197a0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
197b0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
197c0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
197d0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
197e0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
197f0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
19800 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
19810 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
19820 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
19830 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
19840 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
19850 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
19860 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
19870 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
19880 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
19890 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
198a0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
198b0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
198c0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
198d0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
198e0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
198f0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
19900 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
19910 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
19920 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
19930 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
19940 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
19950 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
19960 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
19970 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
19980 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
19990 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
199a0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
199b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
199c0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
199d0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
199e0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
199f0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
19a00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
19a10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
19a20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
19a30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
19a40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
19a50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
19a60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
19a70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
19a80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
19a90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
19aa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
19ab0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
19ac0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
19ad0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
19ae0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
19af0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
19b00 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
19b10 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
19b20 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
19b30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
19b40 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
19b50 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
19b60 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
19b70 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
19b80 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
19b90 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
19ba0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
19bb0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
19bc0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
19bd0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
19be0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
19bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19c00 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
19c10 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
19c20 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
19c30 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
19c40 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
19c50 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
19c60 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
19c70 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
19c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19c90 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
19ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
19cb0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
19cc0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 sy handler..*/.S
19cd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
19ce0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
19cf0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
19d00 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
19d10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
19d20 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
19d30 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
19d40 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
19d50 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
19d60 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
19d70 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
19d80 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
19d90 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
19da0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
19db0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
19dc0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
19dd0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
19de0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
19df0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
19e00 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
19e10 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
19e20 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
19e30 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
19e40 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
19e50 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
19e60 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
19e70 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
19e80 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
19e90 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
19ea0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
19eb0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
19ec0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
19ed0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
19ee0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
19ef0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
19f00 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
19f10 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
19f20 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
19f30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
19f40 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
19f50 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
19f60 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
19f70 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
19f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
19f90 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
19fa0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
19fb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
19fc0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
19fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
19fe0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
19ff0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
1a000 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
1a010 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
1a020 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
1a030 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 red.)^.*/.SQLITE
1a040 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1a050 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
1a060 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
1a070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1a080 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
1a090 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
1a0a0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a ng Queries.**.**
1a0b0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 This is a legac
1a0c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 y interface that
1a0d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f is preserved fo
1a0e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
1a0f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 atibility..** Us
1a100 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
1a110 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d ace is not recom
1a120 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 mended..**.** De
1a130 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 finition: A <b>r
1a140 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 esult table</b>
1a150 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 is memory data s
1a160 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 tructure created
1a170 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 by the.** [sqli
1a180 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
1a190 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 interface. A r
1a1a0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f esult table reco
1a1b0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c rds the.** compl
1a1c0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 ete query result
1a1d0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f s from one or mo
1a1e0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a re queries..**.*
1a1f0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 * The table conc
1a200 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e eptually has a n
1a210 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e umber of rows an
1a220 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a d columns. But.
1a230 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 ** these numbers
1a240 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 are not part of
1a250 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1a260 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 e itself. These
1a270 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 .** numbers are
1a280 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 obtained separat
1a290 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 ely. Let N be t
1a2a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
1a2b0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 s.** and M be th
1a2c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1a2d0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 mns..**.** A res
1a2e0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 ult table is an
1a2f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
1a300 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e s to zero-termin
1a310 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
1a320 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 gs..** There are
1a330 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 (N+1)*M element
1a340 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 s in the array.
1a350 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 The first M poi
1a360 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 nters point.** t
1a370 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1a380 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 d strings that
1a390 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 contain the name
1a3a0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
1a3b0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 ..** The remaini
1a3c0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 ng entries all p
1a3d0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 oint to query re
1a3e0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c sults. NULL val
1a3f0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e ues result.** in
1a400 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 NULL pointers.
1a410 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 All other value
1a420 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 s are in their U
1a430 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
1a440 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 ated.** string r
1a450 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 epresentation as
1a460 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1a470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
1a480 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 t()]..**.** A re
1a490 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 sult table might
1a4a0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 consist of one
1a4b0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 or more memory a
1a4c0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 llocations..** I
1a4d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
1a4e0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 pass a result t
1a4f0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f able directly to
1a500 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1a510 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 ]..** A result t
1a520 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 able should be d
1a530 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 eallocated using
1a540 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1a550 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e able()]..**.** ^
1a560 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f (As an example o
1a570 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
1a580 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f le format, suppo
1a590 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c se a query resul
1a5a0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f t.** is as follo
1a5b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1a5c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1a5d0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 Name
1a5e0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 | Age.**
1a5f0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d --------------
1a600 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 ---------.**
1a610 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 Alice
1a620 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 | 43.** B
1a630 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a ob | 28.
1a640 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 ** Cindy
1a650 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f | 21.** </
1a660 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1a670 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 >.**.** There ar
1a680 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d e two column (M=
1a690 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f =2) and three ro
1a6a0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 ws (N==3). Thus
1a6b0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 the.** result t
1a6c0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 able has 8 entri
1a6d0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 es. Suppose the
1a6e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
1a6f0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e stored.** in an
1a700 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 array names azR
1a710 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 esult. Then azR
1a720 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 esult holds this
1a730 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 content:.**.**
1a740 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1a750 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 >.** azRe
1a760 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e sult[0] = "N
1a770 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ame";.**
1a780 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 azResult[1]
1a790 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 = "Age";.**
1a7a0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1a7b0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 2] = "Alice";.**
1a7c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1a7d0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a [3] = "43";.
1a7e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1a7f0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 lt[4] = "Bob
1a800 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1a810 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 esult[5] = "
1a820 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 28";.** a
1a830 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d zResult[6] =
1a840 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 "Cindy";.**
1a850 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1a860 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c ;7] = "21";.** <
1a870 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1a880 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1a890 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1a8a0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
1a8b0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
1a8c0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
1a8d0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
1a8e0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
1a8f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1a900 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
1a910 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
1a920 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eter and returns
1a930 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
1a940 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 to the.** pointe
1a950 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 r given in its 3
1a960 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a rd parameter..**
1a970 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 .** After the ap
1a980 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 plication has fi
1a990 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 nished with the
1a9a0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 result from sqli
1a9b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
1a9c0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 .** it must pass
1a9d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1a9e0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c e pointer to sql
1a9f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1aa00 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a ) in order to.**
1aa10 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1aa20 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c ory that was mal
1aa30 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 loced. Because
1aa40 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a of the way the.*
1aa50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
1aa60 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 c()] happens wit
1aa70 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hin sqlite3_get_
1aa80 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c table(), the cal
1aa90 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ling.** function
1aaa0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f must not try to
1aab0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 call [sqlite3_f
1aac0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e ree()] directly.
1aad0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 Only.** [sqlit
1aae0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1aaf0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 is able to rele
1ab00 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 ase the memory p
1ab10 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 roperly and safe
1ab20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ly..**.** The sq
1ab30 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1ab40 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
1ab50 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 mplemented as a
1ab60 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a wrapper around.*
1ab70 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * [sqlite3_exec(
1ab80 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 )]. The sqlite3
1ab90 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 _get_table() rou
1aba0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 tine does not ha
1abb0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ve access.** to
1abc0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 any internal dat
1abd0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 a structures of
1abe0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 SQLite. It uses
1abf0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 only the public
1ac00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 .** interface de
1ac10 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 fined here. As
1ac20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 a consequence, e
1ac30 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 rrors that occur
1ac40 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 in the.** wrapp
1ac50 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 er layer outside
1ac60 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c of the internal
1ac70 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1ac80 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a ] call are not.*
1ac90 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 * reflected in s
1aca0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
1acb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
1acc0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 ode()] or.** [sq
1acd0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
1ace0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1acf0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
1ad00 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
1ad10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
1ad20 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
1ad30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1ad40 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
1ad50 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
1ad60 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
1ad70 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
1ad80 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
1ad90 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
1ada0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
1adb0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1adc0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
1add0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
1ade0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
1adf0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1ae00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
1ae10 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1ae20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
1ae30 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
1ae40 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
1ae50 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
1ae60 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 I void sqlite3_f
1ae70 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1ae80 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1ae90 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1aea0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1aeb0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1aec0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1aed0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1aee0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1aef0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1af00 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1af10 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1af20 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 library..**.**
1af30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 ^The sqlite3_mpr
1af40 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
1af50 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
1af60 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
1af70 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
1af80 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
1af90 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
1afa0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
1afb0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1afc0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
1afd0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
1afe0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
1aff0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
1b000 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
1b010 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
1b020 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1b030 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1b040 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
1b050 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
1b060 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
1b070 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
1b080 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
1b090 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 (The sqlite3_snp
1b0a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1b0b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
1b0c0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
1b0d0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
1b0e0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
1b0f0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
1b100 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
1b110 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
1b120 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1b130 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
1b140 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
1b150 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1b160 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
1b170 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
1b180 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
1b190 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
1b1a0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
1b1b0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 f().)^ This is
1b1c0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
1b1d0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
1b1e0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
1b1f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
1b200 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
1b210 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e patibility. ^(N
1b220 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 ote also that sq
1b230 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1b240 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f .** returns a po
1b250 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 inter to its buf
1b260 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 fer instead of t
1b270 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1b280 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 characters actua
1b290 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
1b2a0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 the buffer.)^
1b2b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
1b2c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1b2d0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
1b2e0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
1b2f0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
1b300 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
1b310 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
1b320 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1b330 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1b340 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
1b350 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
1b360 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1b370 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 .** ^As long as
1b380 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
1b390 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
1b3a0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
1b3b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
1b3c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
1b3d0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
1b3e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1b3f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a . ^The first.**
1b400 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 parameter "n" i
1b410 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 s the total size
1b420 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 of the buffer,
1b430 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 including space
1b440 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 for.** the zero
1b450 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 terminator. So
1b460 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 the longest stri
1b470 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 ng that can be c
1b480 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 ompletely.** wri
1b490 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 tten will be n-1
1b4a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
1b4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1b4c0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 vsnprintf() rout
1b4d0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 ine is a varargs
1b4e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 version of sqli
1b4f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a te3_snprintf()..
1b500 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1b510 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
1b520 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
1b530 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
1b540 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
1b550 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
1b560 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
1b570 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
1b580 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
1b590 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
1b5a0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
1b5b0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
1b5c0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
1b5d0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
1b5e0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1b5f0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1b600 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1b610 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1b620 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 titutes a null-t
1b630 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1b640 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 ing from the arg
1b650 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 ument list. But
1b660 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 %q also doubles
1b670 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 every '\'' char
1b680 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 acter..** %q is
1b690 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 designed for use
1b6a0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 inside a string
1b6b0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 literal.)^ By
1b6c0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
1b6d0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
1b6e0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
1b6f0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
1b700 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
1b710 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
1b720 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
1b730 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
1b740 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
1b750 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
1b760 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
1b770 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1b780 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1b790 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
1b7a0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
1b7b0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
1b7c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1b7d0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
1b7e0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
1b7f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
1b800 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1b810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b820 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
1b830 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
1b840 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
1b850 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
1b860 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
1b870 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
1b880 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
1b890 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
1b8a0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
1b8b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1b8c0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
1b8d0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
1b8e0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
1b8f0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
1b900 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
1b910 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
1b920 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
1b930 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1b940 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1b950 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
1b960 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
1b970 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
1b980 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
1b990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1b9a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
1b9b0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
1b9c0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
1b9d0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
1b9e0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
1b9f0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
1ba00 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
1ba10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1ba20 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
1ba30 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
1ba40 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
1ba50 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
1ba60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1ba70 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
1ba80 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
1ba90 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
1baa0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
1bab0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
1bac0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
1bad0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
1bae0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
1baf0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
1bb00 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ral..**.** ^(The
1bb10 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
1bb20 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
1bb30 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
1bb40 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
1bb50 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
1bb60 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
1bb70 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
1bb80 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
1bb90 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
1bba0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
1bbb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
1bbc0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
1bbd0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
1bbe0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
1bbf0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 le quotes).)^ S
1bc00 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 o, for example,
1bc10 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a one could say:.*
1bc20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1bc30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1bc40 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
1bc50 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
1bc60 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
1bc70 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a S(%Q)", zText);.
1bc80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
1bc90 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
1bca0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
1bcb0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
1bcc0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1bcd0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f te>.**.** The co
1bce0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 de above will re
1bcf0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 nder a correct S
1bd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
1bd10 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 the zSQL.** vari
1bd20 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 able even if the
1bd30 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 zText variable
1bd40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1bd50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 r..**.** ^(The "
1bd60 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
1bd70 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1bd80 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
1bd90 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
1bda0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
1bdb0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
1bdc0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
1bdd0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
1bde0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
1bdf0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
1be00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1be10 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
1be20 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1be30 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1be40 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 ar*,...);.SQLITE
1be50 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
1be60 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
1be70 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1be80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 );.SQLITE_API ch
1be90 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
1bea0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
1beb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
1bec0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1bed0 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 r *sqlite3_vsnpr
1bee0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
1bef0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
1bf00 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ist);../*.** CAP
1bf10 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
1bf20 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 location Subsyst
1bf30 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c em.**.** The SQL
1bf40 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 ite core uses th
1bf50 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e ese three routin
1bf60 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 es for all of it
1bf70 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 s own.** interna
1bf80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
1bf90 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 ion needs. "Core
1bfa0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 " in the previou
1bfb0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f s sentence.** do
1bfc0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f es not include o
1bfd0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
1bfe0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 specific VFS imp
1bff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 lementation. Th
1c000 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 e.** Windows VFS
1c010 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c uses native mal
1c020 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
1c030 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 for some operat
1c040 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions..**.** ^The
1c050 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c060 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
1c070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1c080 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d block.** of mem
1c090 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 ory at least N b
1c0a0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 ytes in length,
1c0b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 where N is the p
1c0c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
1c0d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c0e0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
1c0f0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
1c100 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
1c110 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
1c120 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 LL pointer. ^If
1c130 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e the parameter N
1c140 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d to.** sqlite3_m
1c150 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
1c160 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e or negative then
1c170 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c180 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e ) returns.** a N
1c190 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
1c1a0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
1c1b0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
1c1c0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
1c1d0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
1c1e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
1c1f0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1c200 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
1c210 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
1c220 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
1c230 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e ht be reused. ^
1c240 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 The sqlite3_free
1c250 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a () routine is.**
1c260 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 a no-op if is c
1c270 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
1c280 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 L pointer. Pass
1c290 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
1c2a0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 er.** to sqlite3
1c2b0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c _free() is harml
1c2c0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e ess. After bein
1c2d0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a g freed, memory.
1c2e0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 ** should neithe
1c2f0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 r be read nor wr
1c300 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 itten. Even rea
1c310 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 ding previously
1c320 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 freed.** memory
1c330 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 might result in
1c340 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1c350 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 ault or other se
1c360 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d vere error..** M
1c370 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e emory corruption
1c380 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e , a segmentation
1c390 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 fault, or other
1c3a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a severe error.**
1c3b0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 might result if
1c3c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1c3d0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1c3e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
1c3f0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f r that.** was no
1c400 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 t obtained from
1c410 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1c420 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
1c430 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 loc()..**.** ^(T
1c440 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1c450 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 oc() interface a
1c460 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a ttempts to resiz
1c470 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d e a.** prior mem
1c480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
1c490 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 o be at least N
1c4a0 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 bytes, where N i
1c4b0 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 s the.** second
1c4c0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
1c4d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1c4e0 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 n to be resized
1c4f0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
1c500 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 parameter.)^ ^ I
1c510 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 f the first para
1c520 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1c530 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 _realloc().** is
1c540 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1c550 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f then its behavio
1c560 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 r is identical t
1c570 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c o calling.** sql
1c580 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 ite3_malloc(N) w
1c590 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1c5a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
1c5b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1c5c0 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 c()..** ^If the
1c5d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1c5e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
1c5f0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
1c600 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 .** negative the
1c610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
1c620 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
1c630 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a me as calling.**
1c640 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 sqlite3_free(P)
1c650 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 where P is the
1c660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1c670 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1c680 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 oc()..** ^sqlite
1c690 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
1c6a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1c6b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1c6c0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1c6d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1c6e0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 ize or NULL if s
1c6f0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
1c700 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
1c710 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1c720 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
1c730 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
1c740 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
1c750 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
1c760 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
1c770 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
1c780 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
1c790 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
1c7a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
1c7b0 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 lloc() and the p
1c7c0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1c7d0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 is freed..** ^If
1c7e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1c7f0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c () returns NULL,
1c800 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 then the prior
1c810 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 allocation.** is
1c820 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
1c830 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 * ^The memory re
1c840 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1c850 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 3_malloc() and s
1c860 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1c870 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c .** is always al
1c880 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 igned to at leas
1c890 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e t an 8 byte boun
1c8a0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a dary, or to a.**
1c8b0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 4 byte boundary
1c8c0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1c8d0 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 4_BYTE_ALIGNED_M
1c8e0 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 ALLOC] compile-t
1c8f0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 ime.** option is
1c900 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 used..**.** In
1c910 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1c920 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 .5.0 and 3.5.1,
1c930 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 it was possible
1c940 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 to define.** the
1c950 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d SQLITE_OMIT_MEM
1c960 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 ORY_ALLOCATION w
1c970 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 hich would cause
1c980 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a the built-in.**
1c990 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1c9a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1c9b0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e s to be omitted.
1c9c0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 That capabilit
1c9d0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 y.** is no longe
1c9e0 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c r provided. Onl
1c9f0 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 y built-in memor
1ca00 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e y allocators can
1ca10 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 be used..**.**
1ca20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 The Windows OS i
1ca30 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 nterface layer c
1ca40 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 alls.** the syst
1ca50 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1ca60 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1ca70 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1ca80 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1ca90 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1caa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1cab0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1cac0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1cad0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1cae0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1caf0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1cb00 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1cb10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1cb20 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 rrors are detect
1cb30 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
1cb40 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 are reported bac
1cb50 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e k as [SQLITE_CAN
1cb60 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 TOPEN] or.** [SQ
1cb70 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 LITE_IOERR] rath
1cb80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
1cb90 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 NOMEM]..**.** Th
1cba0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 e pointer argume
1cbb0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f nts to [sqlite3_
1cbc0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c free()] and [sql
1cbd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a ite3_realloc()].
1cbe0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 ** must be eithe
1cbf0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 r NULL or else p
1cc00 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 ointers obtained
1cc10 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a from a prior.**
1cc20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
1cc30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1cc40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1cc50 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 alloc()] that ha
1cc60 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 ve.** not yet be
1cc70 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a en released..**.
1cc80 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
1cc90 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 on must not read
1cca0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 or write any pa
1ccb0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b rt of.** a block
1ccc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 of memory after
1ccd0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c it has been rel
1cce0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b eased using.** [
1ccf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1cd00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
1cd10 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 loc()]..*/.SQLIT
1cd20 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
1cd30 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
1cd40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1cd50 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
1cd60 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 c(void*, int);.S
1cd70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
1cd80 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 qlite3_free(void
1cd90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1cda0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
1cdb0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 cator Statistics
1cdc0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 .**.** SQLite pr
1cdd0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f ovides these two
1cde0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 interfaces for
1cdf0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 reporting on the
1ce00 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 status.** of th
1ce10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f e [sqlite3_mallo
1ce20 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 c()], [sqlite3_f
1ce30 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ree()], and [sql
1ce40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a ite3_realloc()].
1ce50 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 ** routines, whi
1ce60 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c ch form the buil
1ce70 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
1ce80 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
1ce90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
1cea0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1ceb0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 d()] routine ret
1cec0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
1ced0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d of bytes.** of m
1cee0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 emory currently
1cef0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c outstanding (mal
1cf00 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 loced but not fr
1cf10 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 eed)..** ^The [s
1cf20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1cf30 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 ghwater()] routi
1cf40 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d ne returns the m
1cf50 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 aximum.** value
1cf60 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f of [sqlite3_memo
1cf70 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 ry_used()] since
1cf80 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 the high-water
1cf90 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 mark.** was last
1cfa0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 reset. ^The va
1cfb0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1cfd0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
1cfe0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1cff0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 highwater()] inc
1d000 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 lude any overhea
1d010 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 d.** added by SQ
1d020 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c Lite in its impl
1d030 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 ementation of [s
1d040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1d050 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 ,.** but not ove
1d060 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 rhead added by t
1d070 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e he any underlyin
1d080 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 g system library
1d090 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 .** routines tha
1d0a0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f t [sqlite3_mallo
1d0b0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a c()] may call..*
1d0c0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 *.** ^The memory
1d0d0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
1d0e0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 is reset to the
1d0f0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
1d100 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 f.** [sqlite3_me
1d110 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 mory_used()] if
1d120 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
1d130 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
1d140 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1d150 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 highwater()] is
1d160 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 true. ^The valu
1d170 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 e returned.** by
1d180 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1d190 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 _highwater(1)] i
1d1a0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 s the high-water
1d1b0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 mark.** prior t
1d1c0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a o the reset..*/.
1d1d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
1d1e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
1d1f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 _memory_used(voi
1d200 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 d);.SQLITE_API s
1d210 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
1d220 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1d230 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 water(int resetF
1d240 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 lag);../*.** CAP
1d250 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 I3REF: Pseudo-Ra
1d260 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 ndom Number Gene
1d270 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 rator.**.** SQLi
1d280 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
1d290 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
1d2a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
1d2b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
1d2c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
1d2d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 ct random [ROWID
1d2e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 | ROWIDs] when
1d2f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
1d300 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
1d310 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
1d320 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
1d330 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f est possible [RO
1d340 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 WID]. The PRNG
1d350 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 is also used for
1d360 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e .** the build-in
1d370 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 random() and ra
1d380 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 ndomblob() SQL f
1d390 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 unctions. This
1d3a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
1d3b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
1d3c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 to access the s
1d3d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 ame PRNG for oth
1d3e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a er purposes..**.
1d3f0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 ** ^A call to th
1d400 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 is routine store
1d410 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e s N bytes of ran
1d420 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 domness into buf
1d430 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fer P..**.** ^Th
1d440 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 e first time thi
1d450 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 s routine is inv
1d460 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 oked (either int
1d470 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a ernally or by.**
1d480 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1d490 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 ) the PRNG is se
1d4a0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f eded using rando
1d4b0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a mness obtained.*
1d4c0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 * from the xRand
1d4d0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 omness method of
1d4e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
1d4f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
1d500 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 t..** ^On all su
1d510 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
1d520 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f ions, the pseudo
1d530 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
1d540 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
1d550 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
1d560 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
1d570 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
1d580 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
1d590 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 method..*/.SQLIT
1d5a0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
1d5b0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e e3_randomness(in
1d5c0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a t N, void *P);..
1d5d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1d5e0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 Compile-Time Aut
1d5f0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 horization Callb
1d600 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 acks.**.** ^This
1d610 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 routine registe
1d620 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 rs an authorizer
1d630 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 callback with a
1d640 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
1d650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d660 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 ion], supplied i
1d670 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
1d680 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 ment..** ^The au
1d690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1d6a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
1d6b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
1d6c0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
1d6d0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
1d6e0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
1d6f0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
1d700 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1d710 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1d720 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
1d730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1d740 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 e16_v2()]. ^At
1d750 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
1d760 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
1d770 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
1d780 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
1d790 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
1d7a0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
1d7b0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
1d7c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1d7d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
1d7e0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
1d7f0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
1d800 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 owed. ^The auth
1d810 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1d820 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
1d830 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 [SQLITE_OK] to
1d840 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e allow the action
1d850 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 , [SQLITE_IGNORE
1d860 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 ] to disallow th
1d870 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 e.** specific ac
1d880 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 tion but allow t
1d890 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1d8a0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 to continue to
1d8b0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 be.** compiled,
1d8c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
1d8d0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e to cause the en
1d8e0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 tire SQL stateme
1d8f0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 nt to be.** reje
1d900 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 cted with an err
1d910 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 or. ^If the aut
1d920 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1d930 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
1d940 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
1d950 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1d960 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
1d970 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
1d980 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
1d990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1d9a0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
1d9b0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
1d9c0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
1d9d0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
1d9e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
1d9f0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
1da00 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1da10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1da20 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
1da30 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
1da40 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
1da50 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c . ^When the cal
1da60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
1da70 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
1da80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1da90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
1daa0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
1dab0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
1dac0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 .** authorizer w
1dad0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
1dae0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 error message e
1daf0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a xplaining that.*
1db00 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 * access is deni
1db10 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ed. .**.** ^The
1db20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1db30 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
1db40 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
1db50 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
1db60 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
1db70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 o the sqlite3_se
1db80 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 t_authorizer() i
1db90 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 nterface. ^The s
1dba0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
1dbb0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
1dbc0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1dbd0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
1dbe0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 action code] tha
1dbf0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
1dc00 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
1dc10 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
1dc20 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 rized. ^The thir
1dc30 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 d through sixth
1dc40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
1dc50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
1dc60 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
1dc70 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 d strings that c
1dc80 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 ontain additiona
1dc90 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f l.** details abo
1dca0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f ut the action to
1dcb0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a be authorized..
1dcc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 **.** ^If the ac
1dcd0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
1dce0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e LITE_READ].** an
1dcf0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
1dd00 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 eturns [SQLITE_I
1dd10 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a GNORE] then the.
1dd20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
1dd30 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e tement] statemen
1dd40 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 t is constructed
1dd50 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a to substitute.*
1dd60 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 * a NULL value i
1dd70 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
1dd80 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
1dd90 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 would have.** b
1dda0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c een read if [SQL
1ddb0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e ITE_OK] had been
1ddc0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
1ddd0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a [SQLITE_IGNORE].
1dde0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 ** return can be
1ddf0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e used to deny an
1de00 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 untrusted user
1de10 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 access to indivi
1de20 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 dual.** columns
1de30 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e of a table..** ^
1de40 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
1de50 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 de is [SQLITE_DE
1de60 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 LETE] and the ca
1de70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
1de80 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 * [SQLITE_IGNORE
1de90 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 ] then the [DELE
1dea0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 TE] operation pr
1deb0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a oceeds but the.*
1dec0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 * [truncate opti
1ded0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 mization] is dis
1dee0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f abled and all ro
1def0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 ws are deleted i
1df00 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a ndividually..**.
1df10 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 ** An authorizer
1df20 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 is used when [s
1df30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
1df40 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 preparing].** S
1df50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 QL statements fr
1df60 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 om an untrusted
1df70 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 source, to ensur
1df80 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 e that the SQL s
1df90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 tatements.** do
1dfa0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 not try to acces
1dfb0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 s data they are
1dfc0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 not allowed to s
1dfd0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 ee, or that they
1dfe0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 do not.** try t
1dff0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 o execute malici
1e000 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 ous statements t
1e010 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 hat damage the d
1e020 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a atabase. For.**
1e030 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
1e040 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c lication may all
1e050 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 ow a user to ent
1e060 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 er arbitrary.**
1e070 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 SQL queries for
1e080 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 evaluation by a
1e090 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 database. But t
1e0a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
1e0b0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
1e0c0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 the user to be a
1e0d0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 ble to make arbi
1e0e0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f trary changes to
1e0f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1e100 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 . An authorizer
1e110 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 could then be p
1e120 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c ut in place whil
1e130 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e e the.** user-en
1e140 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 tered SQL is bei
1e150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
1e160 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
1e170 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 that.** disallow
1e180 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 s everything exc
1e190 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 ept [SELECT] sta
1e1a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 tements..**.** A
1e1b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
1e1c0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 need to process
1e1d0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 SQL from untrus
1e1e0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d ted sources.** m
1e1f0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 ight also consid
1e200 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f er lowering reso
1e210 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e urce limits usin
1e220 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
1e230 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 ()].** and limit
1e240 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a ing database siz
1e250 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 e using the [max
1e260 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
1e270 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 AGMA].** in addi
1e280 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e tion to using an
1e290 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
1e2a0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 ** ^(Only a sing
1e2b0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 le authorizer ca
1e2c0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e n be in place on
1e2d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
1e2e0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 ection.** at a t
1e2f0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 ime. Each call
1e300 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
1e310 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 uthorizer overri
1e320 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 des the.** previ
1e330 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 ous call.)^ ^Di
1e340 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 sable the author
1e350 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 izer by installi
1e360 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 ng a NULL callba
1e370 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f ck..** The autho
1e380 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 rizer is disable
1e390 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
1e3a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
1e3b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
1e3c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
1e3d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
1e3e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
1e3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
1e400 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 t invoked the au
1e410 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1e420 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 k..** Note that
1e430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e440 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
1e450 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
1e460 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
1e470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1e480 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
1e490 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
1e4a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
1e4b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e aph..**.** ^When
1e4c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e4d0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
1e4e0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
1e4f0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
1e500 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
1e510 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 e re-prepared du
1e520 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ring [sqlite3_st
1e530 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a ep()] due to a .
1e540 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 ** schema change
1e550 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 . Hence, the ap
1e560 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
1e570 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
1e580 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 .** correct auth
1e590 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1e5a0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 remains in place
1e5b0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c during the [sql
1e5c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
1e5d0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 .** ^Note that t
1e5e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1e5f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1e600 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
1e610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e620 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
1e630 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
1e640 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
1e650 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
1e660 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
1e670 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
1e680 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
1e690 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
1e6a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
1e6b0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
1e6c0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
1e6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
1e6e0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
1e6f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
1e700 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
1e710 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 change..*/.SQLIT
1e720 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1e730 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1e740 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
1e750 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
1e760 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
1e770 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1e780 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
1e790 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
1e7a0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
1e7b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1e7c0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
1e7d0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
1e7e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1e7f0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1e800 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
1e810 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
1e820 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
1e830 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
1e840 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
1e850 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
1e860 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
1e870 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
1e880 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
1e890 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
1e8a0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
1e8b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1e8c0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
1e8d0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
1e8e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
1e8f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
1e900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1e910 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f ENY 1 /* Abo
1e920 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
1e930 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 ment with an err
1e940 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
1e950 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 LITE_IGNORE 2
1e960 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 /* Don't allow a
1e970 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 ccess, but don't
1e980 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 generate an err
1e990 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 or */../*.** CAP
1e9a0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
1e9b0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a r Action Codes.*
1e9c0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
1e9d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1e9e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
1e9f0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
1ea00 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 ck function.** t
1ea10 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 hat is invoked t
1ea20 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 o authorize cert
1ea30 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ain SQL statemen
1ea40 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a t actions. The.
1ea50 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
1ea60 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
1ea70 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
1ea80 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 r code that spec
1ea90 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 ifies.** what ac
1eaa0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 tion is being au
1eab0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 thorized. These
1eac0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 are the integer
1ead0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 action codes th
1eae0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 at.** the author
1eaf0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 izer callback ma
1eb00 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a y be passed..**.
1eb10 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 ** These action
1eb20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e code values sign
1eb30 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 ify what kind of
1eb40 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f operation is to
1eb50 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 be.** authorize
1eb60 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 d. The 3rd and
1eb70 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 4th parameters t
1eb80 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 o the authorizat
1eb90 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 ion.** callback
1eba0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 function will be
1ebb0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
1ebc0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
1ebd0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a which of these.
1ebe0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 ** codes is used
1ebf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
1ec00 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 arameter. ^(The
1ec10 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
1ec20 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 o the.** authori
1ec30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1ec40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1ec50 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 database ("main"
1ec60 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 , "temp",.** etc
1ec70 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
1ec80 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 .)^ ^The 6th pa
1ec90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
1eca0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1ecb0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d ck.** is the nam
1ecc0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d e of the inner-m
1ecd0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 ost trigger or v
1ece0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 iew that is resp
1ecf0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 onsible for.** t
1ed00 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
1ed10 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
1ed20 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
1ed30 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
1ed40 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 m.** top-level S
1ed50 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a QL code..*/./***
1ed60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ed70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ed80 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a ******** 3rd ***
1ed90 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a ********* 4th **
1eda0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 *********/.#defi
1edb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1edc0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
1edd0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 1 /* Index Nam
1ede0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1edf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1ee00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1ee10 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
1ee20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1ee30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1ee40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ee50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1ee60 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 EMP_INDEX 3
1ee70 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1ee80 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
1ee90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1eea0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1eeb0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 MP_TABLE 4
1eec0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1eed0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1eee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1eef0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1ef00 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 P_TRIGGER 5
1ef10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1ef20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1ef30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1ef40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1ef50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f _VIEW 6 /
1ef60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1ef70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1ef80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1ef90 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 ITE_CREATE_TRIGG
1efa0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a ER 7 /*
1efb0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
1efc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1efd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1efe0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 TE_CREATE_VIEW
1eff0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 8 /*
1f000 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
1f010 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f030 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 E_DELETE
1f040 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 9 /* T
1f050 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1f060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1f070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f080 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 _DROP_INDEX
1f090 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 10 /* In
1f0a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1f0b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1f0c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f0d0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 DROP_TABLE
1f0e0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 11 /* Tab
1f0f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1f100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1f110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1f120 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ROP_TEMP_INDEX
1f130 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 12 /* Inde
1f140 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1f150 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1f160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1f170 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 OP_TEMP_TABLE
1f180 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 13 /* Table
1f190 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1f1a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1f1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1f1c0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 P_TEMP_TRIGGER
1f1d0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 14 /* Trigge
1f1e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1f1f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1f200 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1f210 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
1f220 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 15 /* View Na
1f230 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1f240 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1f250 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1f260 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 TRIGGER
1f270 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 16 /* Trigger
1f280 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1f290 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1f2a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
1f2b0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 IEW 1
1f2c0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 7 /* View Name
1f2d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1f2e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1f2f0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 e SQLITE_INSERT
1f300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 18
1f310 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1f320 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1f330 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1f340 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 SQLITE_PRAGMA
1f350 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 19
1f360 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 /* Pragma Name
1f370 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 1st arg or
1f380 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 NULL */.#define
1f390 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 SQLITE_READ
1f3a0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20
1f3b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1f3c0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
1f3d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f3e0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 QLITE_SELECT
1f3f0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 21
1f400 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
1f410 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f420 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f430 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e LITE_TRANSACTION
1f440 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 22 /
1f450 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
1f460 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1f470 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f480 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 ITE_UPDATE
1f490 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 23 /*
1f4a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1f4b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
1f4c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f4d0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 TE_ATTACH
1f4e0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 24 /*
1f4f0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 Filename
1f500 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f520 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 E_DETACH
1f530 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 25 /* D
1f540 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e atabase Name N
1f550 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1f560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f570 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 _ALTER_TABLE
1f580 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 26 /* Da
1f590 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 tabase Name Ta
1f5a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1f5b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f5c0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 REINDEX
1f5d0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 27 /* Ind
1f5e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c ex Name NUL
1f5f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1f600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
1f610 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 NALYZE
1f620 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 28 /* Tabl
1f630 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1f640 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1f650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1f660 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 EATE_VTABLE
1f670 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 29 /* Table
1f680 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
1f690 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
1f6a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1f6b0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 P_VTABLE
1f6c0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 30 /* Table
1f6d0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
1f6e0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1f6f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 fine SQLITE_FUNC
1f700 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 TION
1f710 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 31 /* NULL
1f720 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f Functio
1f730 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 n Name */.#def
1f740 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 ine SQLITE_SAVEP
1f750 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 OINT
1f760 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 32 /* Operatio
1f770 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e n Savepoin
1f780 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 t Name */.#defi
1f790 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 ne SQLITE_COPY
1f7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1f7b0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 0 /* No longer
1f7c0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 used */../*.**
1f7d0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
1f7e0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
1f7f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
1f800 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1f810 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
1f820 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
1f830 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
1f840 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
1f850 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
1f860 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
1f870 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1f880 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
1f890 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1f8a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
1f8b0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
1f8c0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
1f8d0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
1f8e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
1f8f0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
1f900 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
1f910 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
1f920 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
1f930 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
1f940 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
1f950 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
1f960 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
1f970 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
1f980 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
1f990 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
1f9a0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
1f9b0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
1f9c0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
1f9d0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
1f9e0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
1f9f0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
1fa00 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
1fa10 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
1fa20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
1fa30 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
1fa40 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
1fa50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
1fa60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
1fa70 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
1fa80 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 te3_profile() is
1fa90 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 invoked.** as e
1faa0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
1fab0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 t finishes. ^Th
1fac0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
1fad0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
1fae0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
1faf0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
1fb00 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
1fb10 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
1fb20 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
1fb30 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
1fb40 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 to run. ^The p
1fb50 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a rofile callback.
1fb60 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e ** time is in un
1fb70 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e its of nanosecon
1fb80 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 ds, however the
1fb90 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e current implemen
1fba0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c tation.** is onl
1fbb0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c y capable of mil
1fbc0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 lisecond resolut
1fbd0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c ion so the six l
1fbe0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
1fbf0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 .** digits in th
1fc00 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 e time are meani
1fc10 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 ngless. Future
1fc20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1fc30 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 te.** might prov
1fc40 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f ide greater reso
1fc50 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 lution on the pr
1fc60 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e ofiler callback.
1fc70 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
1fc80 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 _profile() funct
1fc90 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 ion is considere
1fca0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 d experimental a
1fcb0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 nd is.** subject
1fcc0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 to change in fu
1fcd0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
1fce0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
1fcf0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
1fd00 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 ite3_trace(sqlit
1fd10 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 e3*, void(*xTrac
1fd20 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
1fd30 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 har*), void*);.S
1fd40 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1fd50 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
1fd60 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 id *sqlite3_prof
1fd70 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 ile(sqlite3*,.
1fd80 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 void(*xProfile)
1fd90 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1fda0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
1fdb0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 4), void*);../*.
1fdc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
1fdd0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
1fde0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
1fdf0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
1fe00 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c s_handler(D,N,X,
1fe10 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 P) interface cau
1fe20 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ses the callback
1fe30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 .** function X t
1fe40 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 o be invoked per
1fe50 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 iodically during
1fe60 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 long running ca
1fe70 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
1fe80 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c e3_exec()], [sql
1fe90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 ite3_step()] and
1fea0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1feb0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 ble()] for.** da
1fec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1fed0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 n D. An example
1fee0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a use for this.**
1fef0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f interface is to
1ff00 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 keep a GUI upda
1ff10 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 ted during a lar
1ff20 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 ge query..**.**
1ff30 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 ^The parameter P
1ff40 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 is passed throu
1ff50 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 gh as the only p
1ff60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1ff70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
1ff80 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 ction X. ^The p
1ff90 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 arameter N is th
1ffa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
1ffb0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
1ffc0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
1ffd0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
1ffe0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
1fff0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
20000 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
20010 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e ack X..**.** ^On
20020 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
20030 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
20040 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
20050 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
20060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
20070 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
20080 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
20090 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
200a0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
200b0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
200c0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
200d0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
200e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
200f0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
20100 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
20110 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
20120 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
20130 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
20140 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
20150 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
20160 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
20170 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
20180 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
20190 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
201a0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
201b0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
201c0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
201d0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
201e0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
201f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
20200 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
20210 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
20220 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
20230 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
20240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
20250 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
20260 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
20270 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
20280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20290 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
202a0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
202b0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
202c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
202d0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
202e0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
202f0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
20300 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f h..**.*/.SQLITE_
20310 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
20320 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
20330 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
20340 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
20350 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
20360 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 API3REF: Opening
20370 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 A New Database
20380 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a Connection.**.**
20390 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
203a0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
203b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 database file wh
203c0 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 ose name is give
203d0 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 n by the.** file
203e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e name argument. ^
203f0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
20400 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
20410 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
20420 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
20430 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
20440 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
20450 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
20460 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
20470 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
20480 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 open16(). ^(A [d
20490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
204a0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 on] handle is us
204b0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ually.** returne
204c0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e d in *ppDb, even
204d0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
204e0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 urs. The only e
204f0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 xception is that
20500 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 .** if SQLite is
20510 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
20520 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
20530 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ld the [sqlite3]
20540 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 object,.** a NU
20550 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 LL will be writt
20560 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e en into *ppDb in
20570 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 stead of a point
20580 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
20590 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e e3].** object.)^
205a0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 ^(If the databa
205b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
205c0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
205d0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
205e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
205f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
20600 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
20610 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
20620 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b ned.)^ ^The.** [
20630 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
20640 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
20650 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
20660 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
20670 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
20680 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
20690 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
206a0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 he error followi
206b0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 ng a failure of
206c0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 any.** of the sq
206d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 lite3_open() rou
206e0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tines..**.** ^Th
206f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
20700 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
20710 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
20720 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
20730 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
20740 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
20750 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
20760 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
20770 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
20780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
20790 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
207a0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
207b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
207c0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
207d0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
207e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
207f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
20800 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
20810 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
20820 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
20830 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
20840 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
20850 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
20860 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
20870 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
20880 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
20890 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
208a0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
208b0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
208c0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
208d0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
208e0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
208f0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
20900 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
20910 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
20920 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
20930 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
20940 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
20950 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
20960 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
20970 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
20980 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
20990 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
209a0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
209b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
209c0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
209d0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
209e0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c ,.** and/or [SQL
209f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
20a00 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a CACHE] flags:)^.
20a10 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 **.** <dl>.** ^(
20a20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
20a30 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a _READONLY]</dt>.
20a40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
20a50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e ase is opened in
20a60 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e read-only mode.
20a70 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 If the databas
20a80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c e does not.** al
20a90 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 ready exist, an
20aa0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
20ab0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
20ac0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
20ad0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
20ae0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
20af0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
20b00 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
20b10 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
20b20 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
20b30 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
20b40 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
20b50 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
20b60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
20b70 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
20b80 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
20b90 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
20ba0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
20bb0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
20bc0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ned.</dd>)^.**.*
20bd0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
20be0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
20bf0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
20c00 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c REATE]</dt>.** <
20c10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
20c20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
20c30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
20c40 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 g, and is create
20c50 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 d if.** it does
20c60 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 not already exis
20c70 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 t. This is the b
20c80 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
20c90 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a always used for.
20ca0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
20cb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
20cc0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a en16().</dd>)^.*
20cd0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 * </dl>.**.** If
20ce0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
20cf0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
20d00 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f en_v2() is not o
20d10 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d ne of the.** com
20d20 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 binations shown
20d30 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 above or one of
20d40 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 the combinations
20d50 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d shown above com
20d60 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 bined.** with th
20d70 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
20d80 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 OMUTEX], [SQLITE
20d90 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
20da0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
20db0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 N_SHAREDCACHE] a
20dc0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 nd/or [SQLITE_OP
20dd0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
20de0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 flags,.** then
20df0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
20e00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
20e10 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
20e20 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
20e30 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e lag is set, then
20e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
20e50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e nnection.** open
20e60 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 s in the multi-t
20e70 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
20e80 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 mode] as long a
20e90 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 s the single-thr
20ea0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 ead.** mode has
20eb0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 not been set at
20ec0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
20ed0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 start-time. ^If
20ee0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
20ef0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
20f00 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e flag is set then
20f10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
20f20 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a nnection opens.*
20f30 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 * in the seriali
20f40 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
20f50 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 ode] unless sing
20f60 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a le-thread was.**
20f70 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 previously sele
20f80 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d cted at compile-
20f90 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
20fa0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c me..** ^The [SQL
20fb0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
20fc0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
20fd0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
20fe0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a onnection to be.
20ff0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 ** eligible to u
21000 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 se [shared cache
21010 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 mode], regardle
21020 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
21030 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 not shared.** c
21040 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 ache is enabled
21050 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 using [sqlite3_e
21060 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
21070 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 he()]. ^The.**
21080 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 [SQLITE_OPEN_PRI
21090 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 VATECACHE] flag
210a0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
210b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
210c0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 o not.** partici
210d0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 pate in [shared
210e0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e cache mode] even
210f0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 if it is enable
21100 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
21110 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d filename is ":m
21120 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 emory:", then a
21130 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
21140 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 ry in-memory dat
21150 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 abase.** is crea
21160 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e ted for the conn
21170 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 ection. ^This i
21180 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
21190 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 e will vanish wh
211a0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 en.** the databa
211b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
211c0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 closed. Future
211d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
211e0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b ite might.** mak
211f0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f e use of additio
21200 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 nal special file
21210 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e names that begin
21220 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 with the ":" ch
21230 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 aracter..** It i
21240 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
21250 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 at when a databa
21260 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 se filename actu
21270 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 ally does begin
21280 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 with.** a ":" ch
21290 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 aracter you shou
212a0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 ld prefix the fi
212b0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 lename with a pa
212c0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a thname such as.*
212d0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 * "./" to avoid
212e0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a ambiguity..**.**
212f0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
21300 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 e is an empty st
21310 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 ring, then a pri
21320 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a vate, temporary.
21330 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 ** on-disk datab
21340 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 ase will be crea
21350 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 ted. ^This priv
21360 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c ate database wil
21370 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 l be.** automati
21380 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 cally deleted as
21390 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 soon as the dat
213a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
213b0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a is closed..**.*
213c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
213d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
213e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
213f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a the name of the.
21400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ** [sqlite3_vfs]
21410 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
21420 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ines the operati
21430 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
21440 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ace that.** the
21450 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
21460 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 nection should u
21470 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 se. ^If the fou
21480 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
21490 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
214a0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 er then the defa
214b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
214c0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 ] object is used
214d0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
214e0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
214f0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
21500 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
21510 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
21520 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
21530 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
21540 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
21550 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
21560 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
21570 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
21580 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
21590 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
215a0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
215b0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
215c0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
215d0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
215e0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
215f0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
21600 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
21610 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 _open_v2()..*/.S
21620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
21630 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
21640 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
21650 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
21660 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
21670 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
21680 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
21690 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
216a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 b handle */.);.S
216b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
216c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
216d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
216e0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
216f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
21700 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
21710 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
21720 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
21730 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
21740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
21750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21760 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
21770 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
21780 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
21790 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
217a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 lite3 **ppDb,
217b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
217c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
217d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 /. int flags,
217e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 /* F
217f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 lags */. const
21800 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 char *zVfs
21810 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 /* Name of VFS
21820 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a module to use *
21830 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
21840 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 3REF: Error Code
21850 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a s And Messages.*
21860 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
21870 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 3_errcode() inte
21880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
21890 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c e numeric [resul
218a0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 t code] or.** [e
218b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
218c0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 ode] for the mos
218d0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 t recent failed
218e0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
218f0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ll.** associated
21900 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
21910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 e connection]. I
21920 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 f a prior API ca
21930 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 ll failed.** but
21940 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
21950 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 API call succee
21960 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ded, the return
21970 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 value from.** sq
21980 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
21990 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e is undefined. ^
219a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
219b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a nded_errcode().*
219c0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
219d0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 he same except t
219e0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 hat it always re
219f0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 turns the .** [e
21a00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
21a10 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 ode] even when e
21a20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
21a30 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 odes are.** disa
21a40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
21a50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
21a60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 ) and sqlite3_er
21a70 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 rmsg16() return
21a80 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
21a90 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 .** text that de
21aa0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
21ab0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 r, as either UTF
21ac0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
21ad0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 pectively..** ^(
21ae0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
21af0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
21b00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
21b10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a ed internally..*
21b20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
21b30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 n does not need
21b40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 to worry about f
21b50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c reeing the resul
21b60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 t..** However, t
21b70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 he error string
21b80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 might be overwri
21b90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tten or dealloca
21ba0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 ted by.** subseq
21bb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 uent calls to ot
21bc0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
21bd0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 face functions.)
21be0 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ^.**.** When the
21bf0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
21c00 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
21c10 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 in use, it might
21c20 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 be the.** case
21c30 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 that a second er
21c40 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 ror occurs on a
21c50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
21c60 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 in between.** th
21c70 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 e time of the fi
21c80 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 rst error and th
21c90 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 e call to these
21ca0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 interfaces..** W
21cb0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 hen that happens
21cc0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 , the second err
21cd0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 or will be repor
21ce0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a ted since these.
21cf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c ** interfaces al
21d00 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 ways report the
21d10 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 most recent resu
21d20 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a lt. To avoid.**
21d30 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 this, each thre
21d40 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 ad can obtain ex
21d50 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 clusive use of t
21d60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
21d70 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 nection] D.** by
21d80 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
21d90 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 e3_mutex_enter](
21da0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
21db0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 x](D)) before be
21dc0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 ginning.** to us
21dd0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 e D and invoking
21de0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
21df0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f leave]([sqlite3_
21e00 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 db_mutex](D)) af
21e10 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 ter.** all calls
21e20 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 to the interfac
21e30 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 es listed here a
21e40 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a re completed..**
21e50 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 .** If an interf
21e60 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 ace fails with S
21e70 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 QLITE_MISUSE, th
21e80 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 at means the int
21e90 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e erface.** was in
21ea0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c voked incorrectl
21eb0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 y by the applica
21ec0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 tion. In that c
21ed0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f ase, the.** erro
21ee0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
21ef0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f ge may or may no
21f00 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c t be set..*/.SQL
21f10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
21f20 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
21f30 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 te3 *db);.SQLITE
21f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
21f50 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
21f60 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
21f70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
21f80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
21f90 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
21fa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
21fb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
21fc0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 errmsg16(sqlite3
21fd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
21fe0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 REF: SQL Stateme
21ff0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 nt Object.** KEY
22000 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 WORDS: {prepared
22010 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 statement} {pre
22020 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
22030 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 }.**.** An insta
22040 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
22050 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 ct represents a
22060 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 single SQL state
22070 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ment..** This ob
22080 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c ject is variousl
22090 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 y known as a "pr
220a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
220b0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 " or a.** "compi
220c0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e led SQL statemen
220d0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 t" or simply as
220e0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a a "statement"..*
220f0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 *.** The life of
22100 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a a statement obj
22110 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 ect goes somethi
22120 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ng like this:.**
22130 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
22140 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 Create the obje
22150 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
22160 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
22170 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 or a related.**
22180 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a function..*
22190 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 * <li> Bind valu
221a0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 es to [host para
221b0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 meters] using th
221c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
221d0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 ().** inter
221e0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 faces..** <li> R
221f0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
22200 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
22210 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
22220 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
22230 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 > Reset the stat
22240 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
22250 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
22260 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
22270 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
22280 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
22290 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
222a0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
222b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
222c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
222d0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
222e0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 Refer to docume
222f0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 ntation on indiv
22300 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 idual methods ab
22310 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ove for addition
22320 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
22330 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
22340 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d ruct sqlite3_stm
22350 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a t sqlite3_stmt;.
22360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22370 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 Run-time Limits
22380 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e .**.** ^(This in
22390 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 terface allows t
223a0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f he size of vario
223b0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f us constructs to
223c0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f be limited.** o
223d0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 n a connection b
223e0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 y connection bas
223f0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 is. The first p
22400 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
22410 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
22420 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c nection] whose l
22430 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 imit is to be se
22440 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 t or queried. T
22450 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
22460 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 ameter is one of
22470 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 the [limit cate
22480 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 gories] that def
22490 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f ine a.** class o
224a0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 f constructs to
224b0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e be size limited.
224c0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 The third para
224d0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
224e0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 new limit for th
224f0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a at construct.)^.
22500 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 **.** ^If the ne
22510 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 w limit is a neg
22520 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 ative number, th
22530 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 e limit is uncha
22540 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 nged..** ^(For e
22550 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ach limit catego
22560 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ry SQLITE_LIMIT_
22570 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 <i>NAME</i> ther
22580 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 e is a .** [limi
22590 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 ts | hard upper
225a0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 bound].** set at
225b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 compile-time by
225c0 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f a C preprocesso
225d0 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a r macro called.*
225e0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 * [limits | SQLI
225f0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f TE_MAX_<i>NAME</
22600 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c i>]..** (The "_L
22610 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 IMIT_" in the na
22620 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f me is changed to
22630 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 "_MAX_".))^.**
22640 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 ^Attempts to inc
22650 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 rease a limit ab
22660 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 ove its hard upp
22670 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 er bound are.**
22680 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
22690 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 ed to the hard u
226a0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a pper bound..**.*
226b0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 * ^Regardless of
226c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
226d0 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 the limit was ch
226e0 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b anged, the .** [
226f0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
22700 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
22710 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ns the prior val
22720 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e ue of the limit.
22730 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 .** ^Hence, to f
22740 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 ind the current
22750 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 value of a limit
22760 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e without changin
22770 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 g it,.** simply
22780 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 invoke this inte
22790 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 rface with the t
227a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 hird parameter s
227b0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 et to -1..**.**
227c0 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 Run-time limits
227d0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
227e0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 use in applicat
227f0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 ions that manage
22800 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f .** both their o
22810 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 wn internal data
22820 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 base and also da
22830 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 tabases that are
22840 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 controlled.** b
22850 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 y untrusted exte
22860 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 rnal sources. A
22870 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 n example applic
22880 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 ation might be a
22890 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 .** web browser
228a0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e that has its own
228b0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 databases for s
228c0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 toring history a
228d0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 nd.** separate d
228e0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c atabases control
228f0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 led by JavaScrip
22900 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 t applications d
22910 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 ownloaded.** off
22920 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 the Internet.
22930 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 The internal dat
22940 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 abases can be gi
22950 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 ven the.** large
22960 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 , default limits
22970 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e . Databases man
22980 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c aged by external
22990 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 sources can.**
229a0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d be given much sm
229b0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 aller limits des
229c0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 igned to prevent
229d0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 a denial of ser
229e0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 vice.** attack.
229f0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 Developers migh
22a00 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 t also want to u
22a10 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
22a20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
22a30 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 ].** interface t
22a40 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f o further contro
22a50 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e l untrusted SQL.
22a60 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
22a70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 e database.** cr
22a80 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 eated by an untr
22a90 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e usted script can
22aa0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 be contained us
22ab0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f ing the.** [max_
22ac0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
22ad0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 GMA]..**.** New
22ae0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 run-time limit c
22af0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 ategories may be
22b00 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
22b10 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 releases..*/.SQ
22b20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
22b30 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
22b40 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
22b50 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
22b60 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
22b70 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
22b80 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ries.** KEYWORDS
22b90 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
22ba0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 y} {*limit categ
22bb0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ories}.**.** The
22bc0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
22bd0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 ine various perf
22be0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a ormance limits.*
22bf0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f * that can be lo
22c00 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d wered at run-tim
22c10 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
22c20 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
22c30 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 e synopsis of th
22c40 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
22c50 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
22c60 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e is shown below.
22c70 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 .** Additional i
22c80 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 nformation is av
22c90 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 ailable at [limi
22ca0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 ts | Limits in S
22cb0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 QLite]..**.** <d
22cc0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 l>.** ^(<dt>SQLI
22cd0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c TE_LIMIT_LENGTH<
22ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
22cf0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
22d00 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c any string or BL
22d10 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c OB or table row,
22d20 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e in bytes.<dd>)^
22d30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
22d40 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
22d50 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
22d60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
22d70 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
22d80 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 atement, in byte
22d90 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
22da0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
22db0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
22dc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
22dd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
22de0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
22df0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
22e00 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
22e10 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
22e20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
22e30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
22e40 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
22e50 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
22e60 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
22e70 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
22e80 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
22e90 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
22ea0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
22eb0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
22ec0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
22ed0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
22ee0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
22ef0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
22f00 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
22f10 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
22f20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
22f30 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
22f40 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
22f50 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
22f60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
22f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
22f80 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e _OP</dt>.** <dd>
22f90 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
22fa0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f er of instructio
22fb0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 ns in a virtual
22fc0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a machine program.
22fd0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 ** used to imple
22fe0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 ment an SQL stat
22ff0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d ement. This lim
23000 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e it is not curren
23010 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c tly.** enforced,
23020 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 though that mig
23030 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 ht be added in s
23040 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 ome future relea
23050 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e se of.** SQLite.
23060 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
23070 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
23080 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 _FUNCTION_ARG</d
23090 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
230a0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
230b0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 arguments on a f
230c0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a unction.</dd>)^.
230d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
230e0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
230f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
23100 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
23110 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
23120 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
23130 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
23140 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
23150 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
23160 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
23170 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
23180 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
23190 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
231a0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
231b0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
231c0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
231d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
231e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
231f0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
23200 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
23210 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
23220 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
23230 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
23240 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
23250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
23260 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a GER_DEPTH</dt>.*
23270 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
23280 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 m depth of recur
23290 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 sion for trigger
232a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 s.</dd>)^.** </d
232b0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
232c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
232d0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
232e0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
232f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
23300 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
23310 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
23320 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
23330 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
23340 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
23350 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
23360 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
23370 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
23380 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
23390 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
233a0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
233b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
233c0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
233d0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
233e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
233f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
23400 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
23410 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
23420 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
23430 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
23440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
23450 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
23460 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
23470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
23480 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
23490 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
234a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
234b0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
234c0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 TH 10
234d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
234e0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 : Compiling An S
234f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
23500 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
23510 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
23520 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
23530 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
23540 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
23550 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
23560 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
23570 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
23580 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
23590 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
235a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
235b0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
235c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
235d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
235e0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 ** prior success
235f0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
23600 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
23610 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
23620 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
23630 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 _open16()]. The
23640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
23650 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 tion must not ha
23660 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a ve been closed..
23670 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
23680 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c argument, "zSql
23690 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d ", is the statem
236a0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
236b0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 ed, encoded.** a
236c0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
236d0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 r UTF-16. The s
236e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
236f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
23700 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 pare_v2().** int
23710 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
23720 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
23730 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 repare16() and s
23740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
23750 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 _v2().** use UTF
23760 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 -16..**.** ^If t
23770 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
23780 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a t is less than z
23790 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ero, then zSql i
237a0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
237b0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
237c0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e erminator. ^If n
237d0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
237e0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
237f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
23800 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 number of bytes
23810 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
23820 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 ^When nByte is
23830 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
23840 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e he.** zSql strin
23850 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 g ends at either
23860 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 the first '\000
23870 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 ' or '\u0000' ch
23880 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 aracter or.** th
23890 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c e nByte-th byte,
238a0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
238b0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 first. If the c
238c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 aller knows.** t
238d0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 hat the supplied
238e0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 string is nul-t
238f0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 erminated, then
23900 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
23910 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 .** performance
23920 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 advantage to be
23930 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e gained by passin
23940 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
23950 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
23960 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d equal to the num
23970 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
23980 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
23990 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 <i>including</i
239a0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 >.** the nul-ter
239b0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a minator bytes..*
239c0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 *.** ^If pzTail
239d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
239e0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
239f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
23a00 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 first byte.** p
23a10 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
23a20 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 he first SQL sta
23a30 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
23a40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
23a50 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 only.** compile
23a60 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
23a70 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
23a80 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
23a90 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 pointing to.** w
23aa0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
23ab0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a mpiled..**.** ^*
23ac0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 ppStmt is left p
23ad0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d ointing to a com
23ae0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 piled [prepared
23af0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
23b00 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 can be.** execut
23b10 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
23b20 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 3_step()]. ^If
23b30 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f there is an erro
23b40 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 r, *ppStmt is se
23b50 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e t.** to NULL. ^
23b60 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 If the input tex
23b70 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 t contains no SQ
23b80 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 L (if the input
23b90 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 is an empty.** s
23ba0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 tring or a comme
23bb0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 nt) then *ppStmt
23bc0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e is set to NULL.
23bd0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 .** The calling
23be0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 procedure is res
23bf0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c ponsible for del
23c00 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c eting the compil
23c10 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ed.** SQL statem
23c20 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
23c30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 e3_finalize()] a
23c40 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 fter it has fini
23c50 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a shed with it..**
23c60 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 ppStmt may not
23c70 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
23c80 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 On success, the
23c90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
23ca0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 ) family of rout
23cb0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
23cc0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 ITE_OK];.** othe
23cd0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
23ce0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
23cf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
23d00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
23d10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
23d20 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 epare16_v2() int
23d30 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 erfaces are.** r
23d40 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 ecommended for a
23d50 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e ll new programs.
23d60 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 The two older i
23d70 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 nterfaces are re
23d80 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 tained.** for ba
23d90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
23da0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 ility, but their
23db0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 use is discoura
23dc0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ged..** ^In the
23dd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c "v2" interfaces,
23de0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
23df0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 atement.** that
23e00 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 is returned (the
23e10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
23e20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 object) contains
23e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
23e40 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
23e50 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
23e60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
23e70 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
23e80 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 to.** behave dif
23e90 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 ferently in thre
23ea0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e ways:.**.** <o
23eb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 l>.** <li>.** ^I
23ec0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
23ed0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
23ee0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
23ef0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
23f00 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
23f10 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
23f20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
23f30 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
23f40 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
23f50 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
23f60 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
23f70 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c n it again..** <
23f80 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
23f90 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f ** ^When an erro
23fa0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 r occurs, [sqlit
23fb0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
23fc0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
23fd0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 e detailed.** [e
23fe0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b rror codes] or [
23ff0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
24000 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 odes]. ^The leg
24010 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 acy behavior was
24020 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 that.** [sqlite
24030 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 3_step()] would
24040 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 only return a ge
24050 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 neric [SQLITE_ER
24060 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 ROR] result code
24070 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c .** and the appl
24080 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 ication would ha
24090 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
240a0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
240b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a ite3_reset()].**
240c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e in order to fin
240d0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
240e0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
240f0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
24100 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
24110 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
24120 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
24130 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
24140 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
24150 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
24160 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
24170 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 ^If the specific
24180 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 value bound to
24190 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 [parameter | hos
241a0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 t parameter] in
241b0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c the .** WHERE cl
241c0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 ause might influ
241d0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 ence the choice
241e0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f of query plan fo
241f0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a r a statement,.*
24200 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 * then the state
24210 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 ment will be aut
24220 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
24230 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 piled, as if the
24240 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 re had been .**
24250 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c a schema change,
24260 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b on the first [
24270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
24280 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 call following a
24290 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 ny change.** to
242a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
242b0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 d_text | binding
242c0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 s] of that [para
242d0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 meter]. .** ^The
242e0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 specific value
242f0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 of WHERE-clause
24300 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 [parameter] migh
24310 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
24320 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 .** choice of qu
24330 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 ery plan if the
24340 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
24350 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 left-hand side
24360 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f of a [LIKE].** o
24370 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f r [GLOB] operato
24380 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 r or if the para
24390 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 meter is compare
243a0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 d to an indexed
243b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 column.** and th
243c0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 e [SQLITE_ENABLE
243d0 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d _STAT2] compile-
243e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 time option is e
243f0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a nabled..** the .
24400 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c ** </li>.** </ol
24410 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 >.*/.SQLITE_API
24420 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
24430 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
24440 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
24450 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
24460 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
24470 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
24480 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
24490 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
244a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
244b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
244c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
244d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
244e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
244f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
24500 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
24510 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
24520 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
24530 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
24540 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
24550 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
24560 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
24570 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
24580 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
24590 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
245a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
245b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
245c0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
245d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
245e0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
245f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
24600 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
24610 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
24620 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
24630 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
24640 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
24650 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
24660 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
24670 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
24680 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
24690 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
246a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
246b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
246c0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
246d0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 re16(. sqlite3
246e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
246f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
24700 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
24710 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
24720 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
24730 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
24740 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
24750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
24760 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
24770 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
24780 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
24790 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
247a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
247b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
247c0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
247d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
247e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
247f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
24800 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
24810 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
24820 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
24830 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
24840 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
24850 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
24860 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
24870 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
24880 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
24890 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
248a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
248b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
248c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
248d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
248e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
248f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
24900 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
24910 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
24920 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
24930 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
24940 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
24950 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ql */.);../*.**
24960 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
24970 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 ving Statement S
24980 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 QL.**.** ^This i
24990 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
249a0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
249b0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 a saved copy of
249c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a the original.**
249d0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
249e0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 o create a [prep
249f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
24a00 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e if that statemen
24a10 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 t was.** compile
24a20 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
24a30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
24a40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
24a50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
24a60 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
24a70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
24a80 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
24a90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
24aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
24ab0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
24ac0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 SQL Statement Wr
24ad0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 ites The Databas
24ae0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
24af0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
24b00 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 ly(X) interface
24b10 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f returns true (no
24b20 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e n-zero) if.** an
24b30 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 d only if the [p
24b40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24b50 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 t] X makes no di
24b60 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a rect changes to.
24b70 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
24b80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
24b90 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ile..**.** Note
24ba0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f that [applicatio
24bb0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
24bc0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b nctions] or.** [
24bd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 virtual tables]
24be0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 might change the
24bf0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 database indire
24c00 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 ctly as a side e
24c10 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f ffect. .** ^(Fo
24c20 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e r example, if an
24c30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
24c40 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 ines a function
24c50 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a "eval()" that .*
24c60 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 * calls [sqlite3
24c70 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 _exec()], then t
24c80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
24c90 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 statement would
24ca0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 .** change the d
24cb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 atabase file thr
24cc0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 ough side-effect
24cd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
24ce0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
24cf0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 SELECT eval('DE
24d00 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 LETE FROM t1') F
24d10 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 ROM t2;.** </pre
24d20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
24d30 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 *.** But because
24d40 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
24d50 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
24d60 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
24d70 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 base file.** dir
24d80 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 ectly, sqlite3_s
24d90 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 tmt_readonly() w
24da0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 ould still retur
24db0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 n true.)^.**.**
24dc0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e ^Transaction con
24dd0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 trol statements
24de0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c such as [BEGIN],
24df0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c [COMMIT], [ROLL
24e00 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 BACK],.** [SAVEP
24e10 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 OINT], and [RELE
24e20 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 ASE] cause sqlit
24e30 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
24e40 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
24e50 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 e,.** since the
24e60 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 statements thems
24e70 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 elves do not act
24e80 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 ually modify the
24e90 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a database but.**
24ea0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e rather they con
24eb0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 trol the timing
24ec0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 of when other st
24ed0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 atements modify
24ee0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 the .** database
24ef0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d . ^The [ATTACH]
24f00 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 and [DETACH] st
24f10 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 atements also ca
24f20 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 use.** sqlite3_s
24f30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 tmt_readonly() t
24f40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 o return true si
24f50 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 nce, while those
24f60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 statements.** c
24f70 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 hange the config
24f80 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 uration of a dat
24f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24fa0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 , they do not ma
24fb0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ke .** changes t
24fc0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 o the content of
24fd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
24fe0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a les on disk..*/.
24ff0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
25000 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
25010 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d only(sqlite3_stm
25020 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
25030 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
25040 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
25050 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 lue Object.** KE
25060 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
25070 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25080 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
25090 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
250a0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
250b0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
250c0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
250d0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
250e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
250f0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
25100 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
25110 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
25120 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
25130 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
25140 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f es. ^Values sto
25150 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
25160 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
25170 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
25180 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
25190 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
251a0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
251b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
251c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
251d0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
251e0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
251f0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
25200 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
25210 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
25220 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
25230 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
25240 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
25250 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
25260 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
25270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
25280 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
25290 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
252a0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
252b0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
252c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
252d0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
252e0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
252f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
25300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
25310 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
25320 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
25330 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
25340 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
25350 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 x is held. An i
25360 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
25370 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
25380 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
25390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
253a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
253b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
253c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
253d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
253e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
253f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
25400 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
25410 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
25420 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
25430 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
25440 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
25450 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
25460 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
25470 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
25480 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
25490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
254a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
254b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
254c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
254d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
254e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
254f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
25500 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
25510 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
25520 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
25530 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
25540 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
25550 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
25560 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
25570 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
25580 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
25590 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
255a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
255b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
255c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
255d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
255e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
255f0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
25600 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
25610 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
25620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
25630 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
25640 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
25650 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
25660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
25670 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
25680 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
25690 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
256a0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
256b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
256c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
256d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
256e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
256f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
25700 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
25710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
25720 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
25730 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
25740 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
25750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
25760 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
25770 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
25780 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
25790 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
257a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
257b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
257c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
257d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
257e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
257f0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
25800 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
25810 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
25820 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
25830 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
25840 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
25850 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
25860 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
25870 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
25880 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
25890 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
258a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
258b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
258c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
258d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
258e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
258f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
25900 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
25910 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
25920 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
25930 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
25940 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
25950 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
25960 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
25970 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
25980 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
25990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
259a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
259b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
259c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
259d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
259e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
259f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
25a00 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
25a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
25a20 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
25a30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
25a40 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
25a50 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
25a60 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
25a70 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
25a80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
25a90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
25aa0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
25ab0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
25ac0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
25ad0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
25ae0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
25af0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
25b00 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
25b10 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 binding}.**.**
25b20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 ^(In the SQL sta
25b30 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 tement text inpu
25b40 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
25b50 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
25b60 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
25b70 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
25b80 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b replaced by a [
25b90 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 parameter] that
25ba0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 matches one of f
25bb0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 ollowing.** temp
25bc0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c lates:.**.** <ul
25bd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 >.** <li> ?.**
25be0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c <li> ?NNN.** <l
25bf0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> :VVV.** <li>
25c00 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 @VVV.** <li>
25c10 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a $VVV.** </ul>.**
25c20 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c .** In the templ
25c30 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 ates above, NNN
25c40 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e represents an in
25c50 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a teger literal,.*
25c60 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 * and VVV repres
25c70 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d ents an alphanum
25c80 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e eric identifier.
25c90 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 )^ ^The values
25ca0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
25cb0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
25cc0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
25cd0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
25ce0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
25cf0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
25d00 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
25d10 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
25d20 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
25d30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
25d40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
25d50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
25d60 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
25d70 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
25d80 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
25d90 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
25da0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
25db0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
25dc0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
25dd0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 riants..**.** ^T
25de0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
25df0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
25e00 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
25e10 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
25e20 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 ** ^The leftmost
25e30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
25e40 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
25e50 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d . ^When the sam
25e60 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
25e70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
25e80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
25e90 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
25ea0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
25eb0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
25ec0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
25ed0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
25ee0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 e..** ^The index
25ef0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
25f00 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
25f10 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
25f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
25f30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
25f40 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
25f50 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 red. ^The index
25f60 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
25f70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
25f80 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
25f90 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 * ^The NNN value
25fa0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
25fb0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 1 and the [sqli
25fc0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
25fd0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 parameter [SQLIT
25fe0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
25ff0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c _NUMBER] (defaul
26000 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a t value: 999)..*
26010 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
26020 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
26030 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
26040 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
26050 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
26060 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
26070 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
26080 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
26090 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
260a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
260b0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
260c0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
260d0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
260e0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
260f0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
26100 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
26110 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
26120 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
26130 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
26140 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
26150 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
26160 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
26170 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
26180 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
26190 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
261a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
261b0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
261c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
261d0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
261e0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
261f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
26200 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
26210 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
26220 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
26230 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
26240 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
26250 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
26260 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
26270 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 r is called.** t
26280 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
26290 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
262a0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c even if the call
262b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
262c0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 _blob(),.** sqli
262d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
262e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
262f0 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e _text16() fails.
26300 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 .** ^If the fi
26310 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
26320 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
26330 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
26340 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
26350 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
26360 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
26370 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
26380 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
26390 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
263a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
263b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
263c0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
263d0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
263e0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
263f0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
26400 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
26410 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
26420 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
26430 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
26440 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
26450 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
26460 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26470 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
26480 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
26490 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
264a0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
264b0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
264c0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
264d0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
264e0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
264f0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
26500 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
26510 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
26520 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
26530 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
26540 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
26550 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
26560 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
26570 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
26580 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
26590 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
265a0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
265b0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
265c0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
265d0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
265e0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
265f0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
26600 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
26610 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
26620 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
26630 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
26640 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
26650 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
26660 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
26670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
26680 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
26690 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
266a0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
266b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
266c0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
266d0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
266e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
266f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
26700 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
26710 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
26720 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
26730 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
26740 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
26750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26760 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
26770 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
26780 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
26790 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
267a0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
267b0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
267c0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
267d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
267e0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
267f0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
26800 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
26810 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
26820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26830 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
26840 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
26850 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
26860 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
26870 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
26880 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
26890 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
268a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
268b0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
268c0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
268d0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
268e0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
268f0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
26900 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
26910 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
26920 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
26930 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
26940 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
26950 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
26960 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
26970 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
26980 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
26990 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
269a0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
269b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
269c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
269d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
269e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
269f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
26a00 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
26a10 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
26a20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
26a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
26a50 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 nt, int);.SQLITE
26a60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26a70 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
26a80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
26a90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
26aa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
26ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
26ad0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
26ae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
26af0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
26b00 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
26b10 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
26b20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
26b30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
26b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
26b50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
26b60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
26b70 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
26b80 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
26b90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26ba0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
26bb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
26bc0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
26bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
26be0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
26bf0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
26c00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
26c10 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
26c20 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
26c30 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
26c40 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
26c50 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
26c60 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
26c70 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
26c80 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
26c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26ca0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
26cb0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
26cc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
26cd0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
26ce0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
26cf0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
26d00 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
26d10 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
26d20 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
26d30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
26d40 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
26d50 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
26d60 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
26d70 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
26d80 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
26d90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
26da0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
26db0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
26dc0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
26dd0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
26de0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
26df0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
26e00 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
26e10 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
26e20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
26e30 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 e ?NNN form are
26e40 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d used,.** there m
26e50 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ay be gaps in th
26e60 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 e list.)^.**.**
26e70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
26e80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
26e90 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
26ea0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
26eb0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
26ec0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
26ed0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
26ee0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
26ef0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
26f00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
26f10 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ter_count(sqlite
26f20 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
26f30 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
26f40 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 Of A Host Parame
26f50 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ter.**.** ^The s
26f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
26f70 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
26f80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
26f90 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
26fa0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
26fb0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
26fc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26fd0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
26fe0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
26ff0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
27000 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
27010 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
27020 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
27030 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
27040 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
27050 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
27060 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
27070 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
27080 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
27090 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
270a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
270b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
270c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
270d0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
270e0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
270f0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
27100 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
27110 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
27120 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
27130 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
27140 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
27150 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
27160 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
27170 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
27180 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
27190 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
271a0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
271b0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
271c0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
271d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
271e0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
271f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
27200 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
27210 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
27220 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
27230 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
27240 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
27250 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
27260 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
27270 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
27280 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
27290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
272a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
272b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
272c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
272d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
272e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
272f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
27300 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
27310 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
27320 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
27330 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
27340 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
27350 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
27360 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
27370 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
27380 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
27390 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
273a0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
273b0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 e.**.** ^Return
273c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
273d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
273e0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
273f0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
27400 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
27410 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
27420 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
27430 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
27440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
27450 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
27460 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
27470 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
27480 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
27490 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
274a0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
274b0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
274c0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
274d0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
274e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
274f0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
27500 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
27510 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
27520 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
27530 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
27540 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
27550 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
27560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
27570 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
27580 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
27590 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
275a0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
275b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
275c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
275d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
275e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
275f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
27600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27610 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
27620 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
27630 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
27640 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
27650 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
27660 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
27670 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
27680 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
27690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
276a0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
276b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
276c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
276d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
276e0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
276f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
27700 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 L..*/.SQLITE_API
27710 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 int sqlite3_cle
27720 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
27730 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
27740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
27750 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
27760 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
27770 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
27780 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
27790 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
277a0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
277b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
277c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
277d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
277e0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
277f0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
27800 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
27810 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
27820 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
27830 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
27840 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
27850 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
27860 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
27870 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
27880 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
27890 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
278a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
278b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
278c0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
278d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
278e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
278f0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
27900 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
27910 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
27920 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
27930 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
27940 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
27950 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
27960 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27970 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
27980 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
27990 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
279a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
279b0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
279c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
279d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
279e0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
279f0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
27a00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
27a10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
27a20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
27a30 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
27a40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
27a50 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
27a60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
27a70 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
27a80 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
27a90 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
27aa0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
27ab0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
27ac0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
27ad0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
27ae0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
27af0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
27b00 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
27b10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
27b20 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
27b30 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
27b40 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
27b50 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
27b60 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
27b70 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
27b80 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
27b90 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
27ba0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
27bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
27bc0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
27bd0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
27be0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
27bf0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
27c00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
27c10 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
27c20 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
27c30 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
27c40 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
27c50 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
27c60 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
27c70 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
27c80 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
27c90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
27ca0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
27cb0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
27cc0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
27cd0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
27ce0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
27cf0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
27d00 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
27d10 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
27d20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
27d30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
27d40 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
27d50 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
27d60 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
27d70 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
27d80 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
27d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
27da0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
27db0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
27dc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
27dd0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 N);.SQLITE_API c
27de0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
27df0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
27e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
27e10 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
27e20 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
27e30 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
27e40 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 ry Result.**.**
27e50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
27e60 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
27e70 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
27e80 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
27e90 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
27ea0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
27eb0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
27ec0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
27ed0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
27ee0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
27ef0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
27f00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
27f10 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
27f20 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
27f30 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
27f40 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
27f50 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
27f60 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
27f70 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
27f80 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
27f90 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
27fa0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
27fb0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
27fc0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
27fd0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
27fe0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
27ff0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
28000 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
28010 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
28020 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
28030 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
28040 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
28050 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
28060 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
28070 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
28080 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
28090 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
280a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
280b0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
280c0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
280d0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
280e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
280f0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
28100 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
28110 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
28120 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
28130 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
28140 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
28150 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
28160 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
28170 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
28180 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
28190 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
281a0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
281b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
281c0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
281d0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
281e0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
281f0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
28200 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
28210 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
28220 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
28230 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
28240 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
28250 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
28260 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
28270 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
28280 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
28290 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
282a0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
282b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
282c0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
282d0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
282e0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
282f0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
28300 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
28310 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
28320 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
28330 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
28340 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
28350 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
28360 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
28370 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
28380 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
28390 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
283a0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
283b0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
283c0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
283d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
283e0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
283f0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
28400 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
28410 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
28420 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
28430 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
28440 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
28450 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
28460 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
28470 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
28480 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
28490 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
284a0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
284b0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
284c0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
284d0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
284e0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
284f0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
28500 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
28510 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
28520 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
28530 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
28540 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
28550 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
28560 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
28570 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
28580 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
28590 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
285a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
285b0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
285c0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
285d0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
285e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
285f0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
28600 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
28610 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
28620 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
28630 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
28640 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
28650 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
28660 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
28670 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
28680 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
28690 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
286a0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
286b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
286c0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
286d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
286e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
286f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
28700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
28710 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
28720 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
28730 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
28740 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
28750 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
28760 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
28770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
28780 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
28790 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
287a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
287b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
287c0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
287d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
287e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
287f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
28800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
28810 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
28820 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
28830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28840 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
28850 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
28860 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 lt.**.** ^(The f
28870 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
28880 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
28890 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
288a0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
288b0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
288c0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
288d0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
288e0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
288f0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
28900 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
28910 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
28920 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
28930 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
28940 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
28950 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
28960 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
28970 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 eturned.)^ ^If
28980 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
28990 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
289a0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
289b0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
289c0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
289d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
289e0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 d..** ^The retur
289f0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
28a00 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
28a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 ed..**.** ^(For
28a20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
28a30 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
28a40 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
28a50 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
28a60 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
28a70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
28a80 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
28a90 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
28aa0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
28ab0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
28ac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
28ad0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
28ae0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
28af0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
28b00 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
28b10 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
28b20 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
28b30 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
28b40 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a olumn (i==0).)^.
28b50 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
28b60 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
28b70 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f ime typing. ^So
28b80 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
28b90 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
28ba0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
28bb0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
28bc0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
28bd0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
28be0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
28bf0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
28c00 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
28c10 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
28c20 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
28c30 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
28c40 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
28c50 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 tic. ^Type.** i
28c60 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
28c70 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c h individual val
28c80 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 ues, not with th
28c90 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 e containers.**
28ca0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f used to hold tho
28cb0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 se values..*/.SQ
28cc0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
28cd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
28ce0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
28cf0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
28d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
28d10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
28d20 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
28d30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
28d40 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
28d50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
28d60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
28d70 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
28d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28d90 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
28da0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
28db0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
28dc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
28dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28de0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
28df0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
28e00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
28e10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
28e20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
28e30 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
28e40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
28e50 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
28e60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
28e70 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
28e80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
28e90 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
28ea0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
28eb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
28ec0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
28ed0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
28ee0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
28ef0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
28f00 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
28f10 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
28f20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
28f30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
28f40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
28f50 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
28f60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
28f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28f80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
28f90 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
28fa0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
28fb0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
28fc0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
28fd0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
28fe0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
28ff0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
29000 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
29010 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
29020 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
29030 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
29040 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
29050 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
29060 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
29070 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
29080 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
29090 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
290a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
290b0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
290c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
290d0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
290e0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
290f0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
29100 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
29110 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
29120 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
29130 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
29140 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
29150 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
29160 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
29170 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
29180 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
29190 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
291a0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
291b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
291c0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
291d0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
291e0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
291f0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
29200 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
29210 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
29220 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
29230 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
29240 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
29250 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 n a.** explicit
29260 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
29270 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
29280 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
29290 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
292a0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
292b0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 ^[SQLITE_DONE]
292c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
292d0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
292e0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
292f0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
29300 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
29310 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
29320 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
29330 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
29340 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
29350 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
29360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
29370 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
29380 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
29390 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
293a0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
293b0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 ^If the SQL stat
293c0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 ement being exec
293d0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 uted returns any
293e0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c data, then [SQL
293f0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 ITE_ROW].** is r
29400 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
29410 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
29420 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 ata is ready for
29430 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 processing by t
29440 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 he.** caller. Th
29450 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
29460 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 accessed using t
29470 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 he [column acces
29480 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a s functions]..**
29490 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
294a0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 is called again
294b0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 to retrieve the
294c0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 next row of data
294d0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
294e0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
294f0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
29500 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
29510 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
29520 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
29530 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
29540 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
29550 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
29560 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
29570 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
29580 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
29590 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
295a0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e _errmsg()]..** ^
295b0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
295c0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
295d0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
295e0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
295f0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
29600 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
29610 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
29620 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
29630 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
29640 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
29650 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
29660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
29670 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
29680 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e statement]. ^In
29690 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
296a0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
296b0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
296c0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
296d0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
296e0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
296f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
29700 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
29710 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
29720 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
29730 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
29740 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
29750 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 led on a [prepar
29760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
29770 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 at has.** alread
29780 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f y been [sqlite3_
29790 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
297a0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 ized] or on one
297b0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 that had.** prev
297c0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 iously returned
297d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f [SQLITE_ERROR] o
297e0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
297f0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a Or it could.**
29800 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
29810 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 t the same datab
29820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
29830 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 s being used by
29840 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 two or.** more t
29850 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 hreads at the sa
29860 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d me moment in tim
29870 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c e..**.** For all
29880 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
29890 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e ite up to and in
298a0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 cluding 3.6.23.1
298b0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b , a call to.** [
298c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
298d0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 was required af
298e0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ter sqlite3_step
298f0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 () returned anyt
29900 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 hing.** other th
29910 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 an [SQLITE_ROW]
29920 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 before any subse
29930 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
29940 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 of.** sqlite3_s
29950 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 tep(). Failure
29960 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 to reset the pre
29970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
29980 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 using .** [sqlit
29990 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c e3_reset()] woul
299a0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b d result in an [
299b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 SQLITE_MISUSE] r
299c0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 eturn from.** sq
299d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 lite3_step(). B
299e0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e ut after version
299f0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 3.6.23.1, sqlit
29a00 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a e3_step() began.
29a10 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** calling [sqli
29a20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 te3_reset()] aut
29a30 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 omatically in th
29a40 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 is circumstance
29a50 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 rather.** than r
29a60 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
29a70 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 _MISUSE]. This
29a80 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 is not considere
29a90 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 d a compatibilit
29aa0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 y.** break becau
29ab0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 se any applicati
29ac0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 on that ever rec
29ad0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
29ae0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 MISUSE error.**
29af0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 is broken by def
29b00 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 inition. The [S
29b10 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
29b20 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ESET] compile-ti
29b30 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e me option.** can
29b40 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 be used to rest
29b50 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ore the legacy b
29b60 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c ehavior..**.** <
29b70 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
29b80 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 e Alert:</b> In
29b90 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
29ba0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 face, the sqlite
29bb0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 3_step().** API
29bc0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
29bd0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 generic error c
29be0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ode, [SQLITE_ERR
29bf0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
29c00 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 ny.** error othe
29c10 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 r than [SQLITE_B
29c20 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 USY] and [SQLITE
29c30 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
29c40 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c ust call.** [sql
29c50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
29c60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
29c70 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
29c80 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
29c90 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 e.** specific [e
29ca0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 rror codes] that
29cb0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
29cc0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
29cd0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
29ce0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
29cf0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
29d00 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
29d10 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
29d20 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
29d30 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
29d40 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
29d50 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
29d60 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
29d70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
29d80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
29d90 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
29da0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
29db0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
29dc0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
29dd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
29de0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a )] interfaces,.*
29df0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 * then the more
29e00 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
29e10 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 codes] are retur
29e20 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 ned directly.**
29e30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
29e40 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ). The use of t
29e50 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
29e60 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
29e70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
29e80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 int sqlite3_step
29e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
29ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29eb0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 : Number of colu
29ec0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 mns in a result
29ed0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 set.**.** ^The s
29ee0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
29ef0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 t(P) interface r
29f00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
29f10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
29f20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 the.** current r
29f30 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
29f40 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 set of [prepare
29f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a d statement] P..
29f60 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 ** ^If prepared
29f70 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 statement P does
29f80 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 not have result
29f90 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 s ready to retur
29fa0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 n.** (via calls
29fb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
29fc0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c column_int | sql
29fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d ite3_column_*()]
29fe0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
29ff0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f s) then sqlite3_
2a000 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 data_count(P) re
2a010 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 turns 0..** ^The
2a020 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2a030 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 unt(P) routine a
2a040 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 lso returns 0 if
2a050 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 P is a NULL poi
2a060 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 nter..**.** See
2a070 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 also: [sqlite3_c
2a080 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a olumn_count()].*
2a090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a0a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2a0b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2a0c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2a0d0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2a0e0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2a0f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2a100 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2a110 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2a120 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2a130 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2a140 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2a150 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2a160 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2a170 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2a180 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2a190 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2a1a0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2a1b0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2a1c0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2a1d0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2a1e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2a1f0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2a200 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2a210 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2a220 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2a230 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2a240 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2a250 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2a260 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2a270 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2a280 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2a290 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2a2a0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2a2b0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2a2c0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2a2d0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2a2e0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2a2f0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2a300 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2a310 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2a320 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2a330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2a340 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2a350 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2a360 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2a370 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2a380 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2a390 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2a3a0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2a3b0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2a3c0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2a3d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2a3e0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2a3f0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2a400 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2a410 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2a420 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2a430 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2a440 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2a450 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2a460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2a470 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2a480 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2a490 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2a4a0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2a4b0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2a4c0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2a4d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2a4e0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2a4f0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2a500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2a510 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2a520 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2a530 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2a540 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2a550 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2a560 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2a570 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2a580 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2a590 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2a5a0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2a5b0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2a5c0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2a5d0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2a5e0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2a5f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2a600 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2a610 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2a620 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2a630 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2a640 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2a650 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2a660 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2a670 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2a680 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2a690 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2a6a0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2a6b0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2a6c0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2a6d0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2a6e0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2a6f0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2a700 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2a710 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2a720 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2a730 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2a740 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2a750 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2a760 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2a770 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2a780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2a790 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2a7a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2a7b0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2a7c0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2a7d0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2a7e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2a7f0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2a800 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2a810 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2a820 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2a830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2a840 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2a850 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2a860 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2a870 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2a880 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2a890 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2a8a0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2a8b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2a8c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2a8d0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2a8e0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2a8f0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2a900 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2a910 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2a920 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2a930 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2a940 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2a950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a960 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2a970 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2a980 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2a990 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2a9a0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2a9b0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2a9c0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2a9d0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2a9e0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2a9f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2aa00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2aa10 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2aa20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2aa30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2aa40 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2aa50 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2aa60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2aa70 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2aa80 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2aa90 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2aaa0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2aab0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2aac0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2aad0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2aae0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2aaf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2ab00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2ab10 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2ab20 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2ab30 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2ab40 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2ab50 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2ab60 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2ab70 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2ab80 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2ab90 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2aba0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2abb0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2abc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2abd0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2abe0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2abf0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2ac00 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2ac10 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2ac20 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2ac30 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2ac40 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2ac50 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2ac60 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2ac70 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2ac80 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2ac90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2aca0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2acb0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2acc0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2acd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2ace0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2acf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2ad00 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2ad10 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2ad20 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2ad30 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2ad40 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2ad50 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2ad60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2ad70 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2ad80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2ad90 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2ada0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2adb0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2adc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2add0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2ade0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2adf0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2ae00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2ae10 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2ae20 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2ae30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2ae40 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2ae50 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2ae60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2ae70 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2ae80 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2ae90 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2aea0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2aeb0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2aec0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2aed0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2aee0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2aef0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2af00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2af10 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2af20 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2af30 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2af40 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2af50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2af60 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2af70 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2af80 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2af90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2afa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2afb0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2afc0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2afd0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2afe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2aff0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2b000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2b010 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2b020 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2b030 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2b040 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2b050 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2b060 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2b070 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2b080 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2b090 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2b0a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2b0b0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2b0c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2b0d0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2b0e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2b0f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2b100 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2b110 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2b120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2b130 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2b140 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2b150 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2b160 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2b170 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e zero terminated.
2b180 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2b190 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2b1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2b1b0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2b1c0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2b1d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2b1e0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2b1f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2b200 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2b210 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2b220 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2b230 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2b240 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2b250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2b260 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2b270 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2b280 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2b290 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2b2a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2b2b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2b2c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b2d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2b2e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2b2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2b300 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2b310 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2b320 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2b330 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2b340 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2b350 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2b360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2b370 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2b380 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2b390 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2b3a0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2b3b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2b3c0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2b3d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2b3e0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2b3f0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2b400 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2b410 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2b420 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2b430 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2b440 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2b450 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2b460 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2b470 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2b480 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2b490 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2b4a0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2b4b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2b4c0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2b4d0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2b4e0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2b4f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2b500 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2b510 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2b520 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2b530 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2b540 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2b550 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2b560 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2b570 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2b580 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2b590 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2b5a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2b5b0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2b5c0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2b5d0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2b5e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2b5f0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2b600 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2b610 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2b620 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2b630 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2b640 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2b650 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2b660 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2b670 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
2b680 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
2b690 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
2b6a0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
2b6b0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2b6c0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2b6d0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
2b6e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2b6f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2b700 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
2b710 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
2b720 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
2b730 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
2b740 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 > Convert from f
2b750 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a loat to integer.
2b760 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
2b770 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
2b780 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2b790 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2b7a0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2b7b0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
2b7c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
2b7d0 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 ame as FLOAT->TE
2b7e0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
2b7f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
2b800 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 EGER <td> Use
2b810 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2b820 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2b830 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2b840 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 Use atof().** <t
2b850 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2b860 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2b870 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
2b880 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
2b890 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
2b8a0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
2b8b0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
2b8c0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2b8d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2b8e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2b8f0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 Convert to TEXT
2b900 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a then use atof().
2b910 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2b920 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
2b930 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
2b940 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
2b950 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
2b960 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
2b970 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 uote>)^.**.** Th
2b980 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 e table above ma
2b990 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f kes reference to
2b9a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
2b9b0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 ary functions at
2b9c0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 oi().** and atof
2b9d0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 (). SQLite does
2b9e0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 not really use
2b9f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2ba00 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 It has its.**
2ba10 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 own equivalent i
2ba20 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 nternal routines
2ba30 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e . The atoi() an
2ba40 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 d atof() names a
2ba50 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 re.** used in th
2ba60 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 e table for brev
2ba70 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 ity and because
2ba80 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 they are familia
2ba90 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 r to most.** C p
2baa0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a rogrammers..**.*
2bab0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
2bac0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2bad0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
2bae0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
2baf0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
2bb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2bb10 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
2bb20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
2bb30 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
2bb40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
2bb50 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
2bb60 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
2bb70 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
2bb80 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
2bb90 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
2bba0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
2bbb0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
2bbc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
2bbd0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2bbe0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
2bbf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2bc00 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
2bc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2bc20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
2bc30 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
2bc40 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
2bc50 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
2bc60 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
2bc70 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
2bc80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2bc90 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
2bca0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
2bcb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
2bcc0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
2bcd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2bce0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
2bcf0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
2bd00 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
2bd10 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
2bd20 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
2bd30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2bd40 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
2bd50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2bd60 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
2bd70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
2bd80 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
2bd90 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
2bda0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
2bdb0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
2bdc0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
2bdd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
2bde0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
2bdf0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
2be00 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
2be10 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
2be20 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
2be30 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
2be40 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
2be50 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
2be60 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
2be70 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
2be80 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
2be90 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
2bea0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
2beb0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
2bec0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
2bed0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
2bee0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
2bef0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
2bf00 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
2bf10 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
2bf20 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
2bf30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
2bf40 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
2bf50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
2bf60 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
2bf70 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
2bf80 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
2bf90 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2bfa0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
2bfb0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
2bfc0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
2bfd0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2bfe0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
2bff0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2c000 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
2c010 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
2c020 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
2c030 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2c040 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
2c050 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
2c060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2c070 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
2c080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c090 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
2c0a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2c0b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
2c0c0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
2c0d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2c0e0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
2c0f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
2c100 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2c110 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
2c120 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
2c130 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
2c140 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
2c150 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
2c160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2c170 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
2c180 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c190 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
2c1a0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
2c1b0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
2c1c0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
2c1d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2c1e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
2c1f0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
2c200 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2c220 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
2c230 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
2c240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2c250 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
2c260 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
2c270 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
2c280 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 ** ^The pointers
2c290 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
2c2a0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
2c2b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
2c2c0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
2c2d0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
2c2e0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
2c2f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2c300 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
2c310 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2c320 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
2c330 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 ^The memory spac
2c340 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 e used to hold s
2c350 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c trings.** and BL
2c360 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 OBs is freed aut
2c370 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 omatically. Do
2c380 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 <b>not</b> pass
2c390 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 the pointers ret
2c3a0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 urned.** [sqlite
2c3b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
2c3c0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
2c3d0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
2c3e0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
2c3f0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
2c400 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
2c410 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
2c420 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
2c430 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
2c440 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
2c450 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
2c460 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
2c470 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
2c480 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
2c490 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
2c4a0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
2c4b0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
2c4c0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
2c4d0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
2c4e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
2c4f0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
2c500 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
2c510 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
2c520 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
2c530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2c540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2c550 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2c560 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2c570 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2c580 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2c5a0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2c5b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2c5c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2c5e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2c5f0 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 _API double sqli
2c600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c te3_column_doubl
2c610 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2c620 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2c630 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2c640 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
2c650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2c660 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
2c670 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
2c680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c690 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
2c6a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2c6b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2c6c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2c6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c6e0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2c6f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2c700 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2c710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2c720 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 umn_text16(sqlit
2c730 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2c740 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
2c750 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2c760 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
2c770 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2c780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
2c790 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 ite3_value *sqli
2c7a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
2c7b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2c7c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a int iCol);../*.*
2c7d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 * CAPI3REF: Dest
2c7e0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 roy A Prepared S
2c7f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
2c800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2c810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
2c820 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
2c830 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
2c840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c850 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f ]..** ^If the mo
2c860 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
2c870 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
2c880 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 ement encountere
2c890 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a d no errors or.*
2c8a0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 * or if the stat
2c8b0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 ement is never b
2c8c0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 een evaluated, t
2c8d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 hen sqlite3_fina
2c8e0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a lize() returns.*
2c8f0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 * SQLITE_OK. ^I
2c900 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2c910 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
2c920 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c statement S fail
2c930 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 ed, then.** sqli
2c940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
2c950 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 returns the appr
2c960 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
2c970 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
2c980 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
2c990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2c9a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2c9b0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2c9c0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
2c9d0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 int during.** th
2c9e0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 e life cycle of
2c9f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ca00 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 ent] S:.** befor
2ca10 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 e statement S is
2ca20 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c ever evaluated,
2ca30 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 after.** one or
2ca40 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b more calls to [
2ca50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2ca60 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 , or after any c
2ca70 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 all.** to [sqlit
2ca80 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 e3_step()] regar
2ca90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
2caa0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 or not the stat
2cab0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d ement has.** com
2cac0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e pleted execution
2cad0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e ..**.** ^Invokin
2cae0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 g sqlite3_finali
2caf0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 ze() on a NULL p
2cb00 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d ointer is a harm
2cb10 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a less no-op..**.*
2cb20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
2cb30 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 n must finalize
2cb40 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 every [prepared
2cb50 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 statement] in or
2cb60 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 der to avoid.**
2cb70 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 resource leaks.
2cb80 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 It is a grievou
2cb90 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 s error for the
2cba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 application to t
2cbb0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 ry to use.** a p
2cbc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2cbd0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
2cbe0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 een finalized.
2cbf0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 Any use of a pre
2cc00 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2cc10 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
2cc20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 been finalized c
2cc30 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 an result in und
2cc40 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e efined and.** un
2cc50 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
2cc60 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 or such as segfa
2cc70 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f ults and heap co
2cc80 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c rruption..*/.SQL
2cc90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2cca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
2ccb0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2ccc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ccd0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
2cce0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2ccf0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
2cd00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 sqlite3_reset()
2cd10 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
2cd20 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 ed to reset a [p
2cd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2cd40 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 t].** object bac
2cd50 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
2cd60 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f state, ready to
2cd70 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e be re-executed.
2cd80 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 .** ^Any SQL sta
2cd90 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 tement variables
2cda0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 that had values
2cdb0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 bound to them u
2cdc0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c sing.** the [sql
2cdd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
2cde0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2cdf0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 ) API] retain th
2ce00 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 eir values..** U
2ce10 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 se [sqlite3_clea
2ce20 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f r_bindings()] to
2ce30 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 reset the bindi
2ce40 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ngs..**.** ^The
2ce50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2ce60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
2ce70 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
2ce80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
2ce90 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 * back to the be
2cea0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 ginning of its p
2ceb0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 rogram..**.** ^I
2cec0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2ced0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2cee0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
2cef0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2cf00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
2cf10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2cf20 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
2cf30 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b ONE],.** or if [
2cf40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2cf50 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 has never befor
2cf60 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e e been called on
2cf70 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c S,.** then [sql
2cf80 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
2cf90 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
2cfa0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 K]..**.** ^If th
2cfb0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2cfc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2cfd0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
2cfe0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2cff0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 tement] S indica
2d000 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 ted an error, th
2d010 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 en.** [sqlite3_r
2d020 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
2d030 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
2d040 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a [error code]..**
2d050 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
2d060 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
2d070 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 rface does not c
2d080 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 hange the values
2d090 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 .** of any [sqli
2d0a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 te3_bind_blob|bi
2d0b0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b ndings] on the [
2d0c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d0d0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nt] S..*/.SQLITE
2d0e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2d0f0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
2d100 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2d110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
2d120 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
2d130 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a SQL Functions.*
2d140 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
2d150 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
2d160 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
2d170 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
2d180 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2d190 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
2d1a0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
2d1b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2d1c0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
2d1d0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2d1e0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
2d1f0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
2d200 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
2d210 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
2d220 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
2d230 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
2d240 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
2d250 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
2d260 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
2d270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
2d280 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
2d290 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
2d2a0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
2d2b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
2d2c0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
2d2d0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
2d2e0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
2d2f0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
2d300 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
2d310 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
2d320 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
2d330 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
2d340 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
2d350 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
2d360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2d370 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
2d380 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
2d390 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2d3a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2d3b0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
2d3c0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
2d3d0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
2d3e0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
2d3f0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
2d400 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
2d410 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
2d420 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
2d430 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2d440 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
2d450 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
2d460 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2d470 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
2d480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
2d490 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2d4a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2d4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
2d4c0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
2d4d0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
2d4e0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
2d4f0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
2d500 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
2d510 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
2d520 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
2d530 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
2d540 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
2d550 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
2d560 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
2d570 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
2d580 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
2d590 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
2d5a0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
2d5b0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
2d5c0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
2d5d0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
2d5e0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
2d5f0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
2d600 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
2d610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
2d620 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
2d630 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
2d640 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
2d650 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
2d660 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
2d670 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
2d680 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
2d690 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
2d6a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
2d6b0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
2d6c0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
2d6d0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
2d6e0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
2d6f0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
2d700 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
2d710 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
2d720 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
2d730 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
2d740 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
2d750 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
2d760 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
2d770 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2d780 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
2d790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
2d7a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
2d7b0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
2d7c0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
2d7d0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
2d7e0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
2d7f0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
2d800 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
2d810 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 rameters. Every
2d820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d SQL function im
2d830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
2d840 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 t be able to wor
2d850 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c k.** with UTF-8,
2d860 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 UTF-16le, or UT
2d870 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d F-16be. But som
2d880 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2d890 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 s may be.** more
2d8a0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 efficient with
2d8b0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 one encoding tha
2d8c0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 n another. ^An
2d8d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a application may.
2d8e0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
2d8f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2d900 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
2d910 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2d920 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 () multiple.** t
2d930 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
2d940 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 me function but
2d950 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 with different v
2d960 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 alues of eTextRe
2d970 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 p..** ^When mult
2d980 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
2d990 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
2d9a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 function are av
2d9b0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a ailable, SQLite.
2d9c0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 ** will pick the
2d9d0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 one that involv
2d9e0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f es the least amo
2d9f0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 unt of data conv
2da00 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 ersion..** If th
2da10 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 ere is only a si
2da20 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ngle implementat
2da30 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e ion which does n
2da40 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 ot care what tex
2da50 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 t.** encoding is
2da60 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 used, then the
2da70 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
2da80 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 should be [SQLIT
2da90 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 E_ANY]..**.** ^(
2daa0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 The fifth parame
2dab0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 ter is an arbitr
2dac0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ary pointer. Th
2dad0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2dae0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 of the.** funct
2daf0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 ion can gain acc
2db00 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e ess to this poin
2db10 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ter using [sqlit
2db20 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
2db30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 )^.**.** ^The si
2db40 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 xth, seventh and
2db50 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 eighth paramete
2db60 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 rs, xFunc, xStep
2db70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 and xFinal, are
2db80 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
2db90 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 C-language funct
2dba0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d ions that implem
2dbb0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
2dbc0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2dbd0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 gate. ^A scalar
2dbe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
2dbf0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
2dc00 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
2dc10 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
2dc20 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e only; NULL poin
2dc30 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 ters must be pas
2dc40 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
2dc50 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 and xFinal.** p
2dc60 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 arameters. ^An a
2dc70 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
2dc80 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
2dc90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2dca0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 of xStep.** and
2dcb0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c xFinal and NULL
2dcc0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 pointer must be
2dcd0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e passed for xFun
2dce0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e c. ^To delete an
2dcf0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c existing.** SQL
2dd00 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
2dd10 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c regate, pass NUL
2dd20 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 L pointers for a
2dd30 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f ll three functio
2dd40 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a n.** callbacks..
2dd50 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e **.** ^(If the n
2dd60 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 inth parameter t
2dd70 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
2dd80 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 _function_v2() i
2dd90 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 s not NULL,.** t
2dda0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 hen it is destru
2ddb0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 ctor for the app
2ddc0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
2ddd0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 inter. .** The d
2dde0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 estructor is inv
2ddf0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 oked when the fu
2de00 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 nction is delete
2de10 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 d, either by bei
2de20 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 ng.** overloaded
2de30 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 or when the dat
2de40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2de50 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 closes.)^.** ^T
2de60 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
2de70 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 also invoked if
2de80 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
2de90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2dea0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 unction_v2() fai
2deb0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 ls..** ^When the
2dec0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c destructor call
2ded0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 back of the tent
2dee0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 h parameter is i
2def0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 nvoked, it.** is
2df00 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 passed a single
2df10 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
2df20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
2df30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
2df40 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 a .** pointer wh
2df50 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 ich was the fift
2df60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2df70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2df80 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a nction_v2()..**.
2df90 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 ** ^It is permit
2dfa0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
2dfb0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
2dfc0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
2dfd0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
2dfe0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2dff0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
2e000 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
2e010 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
2e020 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
2e030 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
2e040 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e xt encodings. ^
2e050 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
2e060 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
2e070 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 ation that most
2e080 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 closely matches
2e090 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
2e0a0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 the.** SQL func
2e0b0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e tion is used. ^
2e0c0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
2e0d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
2e0e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
2e0f0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
2e100 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
2e110 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
2e120 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2e130 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
2e140 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 ive nArg. ^A fu
2e150 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
2e160 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2e170 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
2e180 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
2e190 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
2e1a0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
2e1b0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
2e1c0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
2e1d0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
2e1e0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e .** ^A function
2e1f0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
2e200 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
2e210 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
2e220 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
2e230 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
2e240 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
2e250 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
2e260 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
2e270 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
2e280 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
2e290 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 *.** ^Built-in f
2e2a0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
2e2b0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 overloaded by ne
2e2c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 w application-de
2e2d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e fined functions.
2e2e0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 .**.** ^An appli
2e2f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2e300 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 unction is permi
2e310 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 tted to call oth
2e320 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
2e330 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 erfaces. Howeve
2e340 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 r, such calls mu
2e350 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 st not.** close
2e360 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2e370 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 nection nor fina
2e380 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 lize or reset th
2e390 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
2e3a0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 atement in which
2e3b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
2e3c0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
2e3d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2e3e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2e3f0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
2e400 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
2e410 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
2e420 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
2e430 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
2e440 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
2e450 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
2e460 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2e470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2e480 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
2e490 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2e4a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2e4b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2e4c0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
2e4d0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 3_context*).);.S
2e4e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2e4f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2e500 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ction16(. sqlit
2e510 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
2e520 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e void *zFunctionN
2e530 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
2e540 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2e550 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
2e560 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
2e570 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2e580 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2e590 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
2e5a0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
2e5b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2e5c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2e5d0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
2e5e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
2e5f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2e600 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2e610 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
2e620 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
2e630 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
2e640 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
2e650 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
2e660 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
2e670 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
2e680 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
2e690 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2e6a0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2e6b0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
2e6c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2e6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2e6e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
2e6f0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
2e700 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
2e710 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
2e720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2e730 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
2e740 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
2e750 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
2e760 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
2e770 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
2e780 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
2e790 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
2e7a0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
2e7b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e7c0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
2e7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e7e0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
2e7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e800 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 UTF16BE 3
2e810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e820 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
2e830 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
2e840 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
2e850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
2e860 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
2e870 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
2e880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e eate_function on
2e890 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
2e8a0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
2e8b0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 ED 8 /* sqli
2e8c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2e8d0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
2e8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2e8f0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
2e900 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
2e910 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
2e920 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
2e930 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
2e940 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
2e950 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
2e960 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
2e970 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
2e980 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
2e990 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
2e9a0 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
2e9b0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
2e9c0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
2e9d0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
2e9e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2e9f0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
2ea00 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
2ea10 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
2ea20 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
2ea30 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
2ea40 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 tell you what t
2ea50 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
2ea60 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
2ea70 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
2ea80 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
2ea90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2eaa0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
2eab0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
2eac0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 xt*);.SQLITE_API
2ead0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
2eae0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
2eaf0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
2eb00 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
2eb10 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
2eb20 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
2eb30 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 transfer_binding
2eb40 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
2eb50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b sqlite3_stmt*);
2eb60 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
2eb70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
2eb80 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
2eb90 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
2eba0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
2ebb0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
2ebc0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
2ebd0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
2ebe0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
2ebf0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2ec00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
2ec10 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f alarm(void(*)(vo
2ec20 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 id*,sqlite3_int6
2ec30 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 4,int),void*,sql
2ec40 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
2ec50 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
2ec60 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
2ec70 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 QL Function Para
2ec80 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a meter Values.**.
2ec90 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
2eca0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2ecb0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
2ecc0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
2ecd0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
2ece0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
2ecf0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
2ed00 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
2ed10 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
2ed20 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
2ed30 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 regate..**.** Th
2ed40 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
2ed50 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
2ed60 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
2ed70 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
2ed80 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
2ed90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2eda0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
2edb0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2edc0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
2edd0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
2ede0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
2edf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
2ee00 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
2ee10 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
2ee20 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
2ee30 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
2ee40 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
2ee50 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
2ee60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2ee70 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
2ee80 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
2ee90 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
2eea0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
2eeb0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
2eec0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
2eed0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
2eee0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
2eef0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
2ef00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2ef10 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
2ef20 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
2ef30 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
2ef40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2ef50 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
2ef60 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
2ef70 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
2ef80 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
2ef90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2efa0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
2efb0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
2efc0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
2efd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2efe0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
2eff0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
2f000 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
2f010 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
2f020 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 except that th
2f030 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
2f040 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
2f050 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2f060 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
2f070 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
2f080 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
2f090 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
2f0a0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
2f0b0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
2f0c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
2f0d0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
2f0e0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
2f0f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
2f100 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
2f110 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
2f120 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
2f130 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
2f140 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
2f150 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
2f160 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
2f170 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
2f180 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
2f190 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
2f1a0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
2f1b0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
2f1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
2f1d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
2f1e0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
2f1f0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
2f200 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
2f210 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
2f220 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
2f230 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
2f240 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
2f250 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
2f260 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
2f270 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
2f280 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
2f290 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
2f2a0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
2f2b0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
2f2c0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
2f2d0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
2f2e0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
2f2f0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
2f300 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
2f310 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
2f320 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
2f330 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
2f340 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
2f350 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
2f360 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
2f370 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
2f380 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
2f390 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
2f3a0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
2f3b0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
2f3c0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
2f3d0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
2f3e0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
2f3f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
2f400 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
2f410 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
2f420 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2f430 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
2f440 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
2f450 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
2f460 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
2f470 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
2f480 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2f490 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
2f4a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
2f4b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
2f4c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
2f4d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
2f4e0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
2f4f0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
2f500 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
2f510 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
2f520 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
2f530 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
2f540 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
2f550 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
2f560 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2f570 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
2f580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2f590 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2f5b0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
2f5c0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
2f5d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2f5e0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
2f5f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2f600 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c E_API double sql
2f610 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
2f620 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
2f630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2f640 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
2f650 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
2f660 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
2f670 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
2f680 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
2f690 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 4(sqlite3_value*
2f6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2f6b0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
2f6c0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
2f6d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
2f6e0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
2f6f0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2f700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2f710 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
2f720 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
2f730 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2f740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
2f750 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
2f760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2f770 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2f780 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
2f790 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2f7a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2f7b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2f7c0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2f7d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
2f7e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2f7f0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
2f800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2f810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f820 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
2f830 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
2f840 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
2f850 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
2f860 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2f870 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
2f880 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
2f890 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
2f8a0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
2f8b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
2f8c0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
2f8d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
2f8e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
2f8f0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
2f900 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
2f910 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
2f920 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
2f930 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
2f940 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
2f950 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
2f960 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
2f970 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
2f980 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
2f990 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
2f9a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
2f9b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
2f9c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
2f9d0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
2f9e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
2f9f0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
2fa00 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
2fa10 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
2fa20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
2fa30 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
2fa40 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
2fa50 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
2fa60 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
2fa70 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
2fa80 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
2fa90 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
2faa0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
2fab0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
2fac0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
2fad0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
2fae0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
2faf0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
2fb00 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
2fb10 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
2fb20 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
2fb30 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
2fb40 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
2fb50 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
2fb60 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
2fb70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2fb80 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
2fb90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
2fba0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
2fbb0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
2fbc0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
2fbd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
2fbe0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
2fbf0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
2fc00 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
2fc10 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 er if N is.** le
2fc20 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
2fc30 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
2fc40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
2fc50 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a error occurs..*
2fc60 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e *.** ^(The amoun
2fc70 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 t of space alloc
2fc80 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
2fc90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
2fca0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 t(C,N) is.** det
2fcb0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e ermined by the N
2fcc0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 parameter on fi
2fcd0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 rst successful c
2fce0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 all. Changing t
2fcf0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e he.** value of N
2fd00 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
2fd10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 all to sqlite3_a
2fd20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2fd30 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 () within.** the
2fd40 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
2fd50 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 function instanc
2fd60 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a e will not resiz
2fd70 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 e the memory.**
2fd80 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a allocation.)^.**
2fd90 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f .** ^SQLite auto
2fda0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
2fdb0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
2fdc0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 ated by .** sqli
2fdd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2fde0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 ntext() when the
2fdf0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
2fe00 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
2fe10 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
2fe20 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 meter must be a
2fe30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
2fe40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
2fe50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
2fe60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
2fe70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
2fe80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 ter.** to the xS
2fe90 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 tep or xFinal ca
2fea0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
2feb0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
2fec0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
2fed0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
2fee0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
2fef0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
2ff00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
2ff10 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
2ff20 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
2ff30 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
2ff40 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
2ff50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
2ff60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
2ff70 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
2ff80 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b t*, int nBytes);
2ff90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ffa0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 : User Data For
2ffb0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
2ffc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 ^The sqlite3_use
2ffd0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 r_data() interfa
2ffe0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
2fff0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
30000 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 ter that was the
30010 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d pUserData param
30020 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 eter (the 5th pa
30030 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
30040 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
30050 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
30060 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
30070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
30080 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
30090 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
300a0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
300b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
300c0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
300d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
300e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
300f0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
30100 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
30110 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
30120 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
30130 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
30140 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
30150 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
30160 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
30170 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
30180 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
30190 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
301a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
301b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 The sqlite3_cont
301c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 ext_db_handle()
301d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
301e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
301f0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
30200 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
30210 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 ection] (the 1st
30220 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
30230 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
30240 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
30250 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
30260 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
30270 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
30280 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
30290 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
302a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
302b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
302c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
302d0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 lite3 *sqlite3_c
302e0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
302f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
30300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
30310 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 REF: Function Au
30320 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a xiliary Data.**.
30330 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
30340 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d two functions m
30350 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 ay be used by sc
30360 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
30370 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 ns to.** associa
30380 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 te metadata with
30390 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 argument values
303a0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 . If the same va
303b0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f lue is passed to
303c0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 .** multiple inv
303d0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
303e0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
303f0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 n during query e
30400 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a xecution, under.
30410 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 ** some circumst
30420 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 ances the associ
30430 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 ated metadata ma
30440 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 y be preserved.
30450 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 This may.** be u
30460 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 sed, for example
30470 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c , to add a regul
30480 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 ar-expression ma
30490 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a tching scalar.**
304a0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 function. The c
304b0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 ompiled version
304c0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 of the regular e
304d0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f xpression is sto
304e0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 red as.** metada
304f0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ta associated wi
30500 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 th the SQL value
30510 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 passed as the r
30520 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
30530 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 n.** pattern. T
30540 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 he compiled regu
30550 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
30560 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 an be reused on
30570 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f multiple.** invo
30580 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
30590 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 ame function so
305a0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 that the origina
305b0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 l pattern string
305c0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 .** does not nee
305d0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c d to be recompil
305e0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 ed on each invoc
305f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
30600 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
30610 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
30620 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
30630 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 ter to the metad
30640 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
30650 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
30660 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 _set_auxdata() f
30670 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 unction with the
30680 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a Nth argument.**
30690 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 value to the ap
306a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
306b0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 d function. ^If
306c0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 no metadata has
306d0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 been ever.** bee
306e0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 n set for the Nt
306f0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 h argument of th
30700 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 e function, or i
30710 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 f the correspond
30720 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
30730 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 parameter has ch
30740 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 anged since the
30750 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 meta-data was se
30760 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 t,.** then sqlit
30770 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
30780 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
30790 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
307a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
307b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
307c0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 ace saves the me
307d0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 tadata.** pointe
307e0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 d to by its 3rd
307f0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
30800 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
30810 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
30820 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
30830 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
30840 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 nction. Subsequ
30850 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ent.** calls to
30860 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
30870 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 ata() might retu
30880 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 rn this data, if
30890 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 it has.** not b
308a0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a een destroyed..*
308b0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 * ^If it is not
308c0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c NULL, SQLite wil
308d0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 l invoke the des
308e0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 tructor.** funct
308f0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 ion given by the
30900 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
30910 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
30920 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 xdata() on.** th
30930 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 e metadata when
30940 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
30950 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
30960 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 eter changes.**
30970 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 or when the SQL
30980 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 statement comple
30990 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 tes, whichever c
309a0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a omes first..**.*
309b0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 * SQLite is free
309c0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 to call the des
309d0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 tructor and drop
309e0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 metadata on any
309f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 .** parameter of
30a00 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 any function at
30a10 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 any time. ^The
30a20 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 only guarantee
30a30 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 is that.** the d
30a40 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 estructor will b
30a50 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 e called before
30a60 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
30a70 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e dropped..**.** ^
30a80 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 (In practice, me
30a90 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 tadata is preser
30aa0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
30ab0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
30ac0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
30ad0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
30ae0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
30af0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
30b00 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
30b10 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 and [parameters
30b20 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ].)^.**.** These
30b30 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
30b40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
30b50 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
30b60 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 which.** the SQ
30b70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
30b80 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
30b90 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
30ba0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
30bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
30bc0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f int N);.SQLITE_
30bd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
30be0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
30bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
30c00 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
30c10 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
30c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30c30 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
30c40 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
30c50 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a ructor Behavior.
30c60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
30c70 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
30c80 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
30c90 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
30ca0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
30cb0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
30cc0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
30cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
30ce0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 ob()]. ^If the
30cf0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 destructor.** ar
30d00 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 gument is SQLITE
30d10 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e _STATIC, it mean
30d20 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
30d30 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f nt pointer is co
30d40 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 nstant.** and wi
30d50 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e ll never change.
30d60 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 It does not ne
30d70 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 ed to be destroy
30d80 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c ed. ^The.** SQL
30d90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 ITE_TRANSIENT va
30da0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 lue means that t
30db0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 he content will
30dc0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e likely change in
30dd0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 .** the near fut
30de0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c ure and that SQL
30df0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 ite should make
30e00 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
30e10 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
30e20 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 ontent before re
30e30 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 turning..**.** T
30e40 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 he typedef is ne
30e50 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 cessary to work
30e60 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 around problems
30e70 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b in certain.** C+
30e80 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 + compilers. Se
30e90 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a e ticket #2191..
30ea0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 */.typedef void
30eb0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 (*sqlite3_destru
30ec0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a ctor_type)(void*
30ed0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 );.#define SQLIT
30ee0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 E_STATIC ((
30ef0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
30f00 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 or_type)0).#defi
30f10 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ne SQLITE_TRANSI
30f20 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f ENT ((sqlite3_
30f30 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
30f40 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 -1)../*.** CAPI3
30f50 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 REF: Setting The
30f60 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 Result Of An SQ
30f70 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a L Function.**.**
30f80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
30f90 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
30fa0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
30fb0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
30fc0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
30fd0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
30fe0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
30ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
31000 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
31010 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
31020 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
31030 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
31040 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
31050 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
31060 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
31070 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
31080 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
31090 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
310a0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
310b0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
310c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
310d0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
310e0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
310f0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
31100 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
31110 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
31120 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
31130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
31140 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
31150 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
31160 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
31170 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
31180 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
31190 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
311a0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
311b0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
311c0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
311d0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
311e0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
311f0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
31200 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
31210 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
31220 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
31230 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 _zeroblob() inte
31240 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 rfaces set the r
31250 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
31260 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31270 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
31280 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 be a BLOB contai
31290 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a ning all zero.**
312a0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 bytes and N byt
312b0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 es in size, wher
312c0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 e N is the value
312d0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 of the 2nd para
312e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
312f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
31300 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 _double() interf
31310 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
31320 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
31330 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31340 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
31350 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 e a floating poi
31360 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 nt value specifi
31370 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 ed.** by its 2nd
31380 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
31390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
313a0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
313b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
313c0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
313d0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
313e0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
313f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
31400 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
31410 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
31420 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e the string poin
31430 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a ted to by the.**
31440 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
31450 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 f sqlite3_result
31460 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 _error() or sqli
31470 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
31480 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 16().** as the t
31490 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ext of an error
314a0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 message. ^SQLit
314b0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 e interprets the
314c0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
314d0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
314e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
314f0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e or() as UTF-8. ^
31500 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 SQLite.** interp
31510 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 rets the string
31520 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
31530 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 ult_error16() as
31540 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
31550 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e e.** byte order.
31560 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 ^If the third
31570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
31580 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
31590 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
315a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
315b0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 () is negative t
315c0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
315d0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a as the error.**
315e0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 message all tex
315f0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 t up through the
31600 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
31610 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
31620 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
31630 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
31640 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a ult_error() or.*
31650 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
31660 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f _error16() is no
31670 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 n-negative then
31680 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 SQLite takes tha
31690 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 t many.** bytes
316a0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
316b0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
316c0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 rameter as the e
316d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
316e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
316f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
31700 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31710 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 error16().** rou
31720 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 tines make a pri
31730 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
31740 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
31750 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ext before.** th
31760 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 ey return. Henc
31770 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 e, the calling f
31780 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c unction can deal
31790 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 locate or.** mod
317a0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 ify the text aft
317b0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 er they return w
317c0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
317d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
317e0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 ult_error_code()
317f0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 function change
31800 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
31810 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
31820 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 SQLite as a resu
31830 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 lt of an error i
31840 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e n a function. ^
31850 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 By default,.** t
31860 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 he error code is
31870 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 SQLITE_ERROR.
31880 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ^A subsequent ca
31890 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 ll to sqlite3_re
318a0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
318b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
318c0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 t_error16() rese
318d0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ts the error cod
318e0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f e to SQLITE_ERRO
318f0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 R..**.** ^The sq
31900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f lite3_result_too
31910 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 big() interface
31920 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
31930 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
31940 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
31950 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 at a string or B
31960 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 LOB is too long
31970 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
31980 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31990 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
319a0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
319b0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
319c0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
319d0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
319e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
319f0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e failed..**.** ^
31a00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
31a10 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 lt_int() interfa
31a20 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
31a30 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
31a40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
31a50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
31a60 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 to be the 32-bit
31a70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
31a80 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
31a90 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
31aa0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 nt..** ^The sqli
31ab0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
31ac0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
31ad0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
31ae0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
31af0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31b00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
31b10 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 the 64-bit signe
31b20 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
31b30 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
31b40 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
31b50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31b60 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 _result_null() i
31b70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
31b80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
31b90 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
31ba0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
31bb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c ction to be NULL
31bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
31bd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
31be0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 (), sqlite3_resu
31bf0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 lt_text16(),.**
31c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
31c10 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 ext16le(), and s
31c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31c30 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 xt16be() interfa
31c40 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 ces.** set the r
31c50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
31c60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
31c70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
31c80 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 to be.** a text
31c90 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 string which is
31ca0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 represented as U
31cb0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 TF-8, UTF-16 nat
31cc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a ive byte order,.
31cd0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
31ce0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d endian, or UTF-
31cf0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 16 big endian, r
31d00 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
31d10 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 ^SQLite takes th
31d20 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 e text result fr
31d30 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 om the applicati
31d40 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 on from.** the 2
31d50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
31d60 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
31d70 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
31d80 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ces..** ^If the
31d90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
31da0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
31db0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
31dc0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 aces.** is negat
31dd0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ive, then SQLite
31de0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 takes result te
31df0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 xt from the 2nd
31e00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 parameter.** thr
31e10 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
31e20 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
31e30 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 * ^If the 3rd pa
31e40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
31e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31e60 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
31e70 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 * is non-negativ
31e80 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 e, then as many
31e90 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
31ea0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 cters) of the te
31eb0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f xt.** pointed to
31ec0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
31ed0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 meter are taken
31ee0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 as the applicati
31ef0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 on-defined.** fu
31f00 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a nction result..*
31f10 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
31f20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
31f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31f40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
31f50 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
31f60 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f ult_blob is a no
31f70 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
31f80 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c then SQLite call
31f90 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 s that.** functi
31fa0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 on as the destru
31fb0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 ctor on the text
31fc0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
31fd0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 when it has.** f
31fe0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
31ff0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
32000 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
32010 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
32020 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
32030 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f interfaces or to
32040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
32050 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
32060 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
32070 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 SQLITE_STATIC, t
32080 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 hen SQLite.** as
32090 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 sumes that the t
320a0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
320b0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e lt is in constan
320c0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 t space and does
320d0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 not.** copy the
320e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
320f0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 parameter nor ca
32100 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ll a destructor
32110 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a on the content.*
32120 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 * when it has fi
32130 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
32140 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
32150 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
32160 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
32170 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
32180 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
32190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
321a0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
321b0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
321c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 TE_TRANSIENT.**
321d0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 then SQLite make
321e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
321f0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 result into spac
32200 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a e obtained from.
32210 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
32220 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 _malloc()] befor
32230 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a e it returns..**
32240 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32250 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
32260 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
32270 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
32280 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
32290 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
322a0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
322b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
322c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
322d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
322e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
322f0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a ameter. ^The.**
32300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32310 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
32320 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
32330 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
32340 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 alue].** so that
32350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
32360 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 lue] specified i
32370 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 n the parameter
32380 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a may change or.**
32390 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
323a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 after sqlite3_re
323b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 sult_value() ret
323c0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 urns without har
323d0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 m..** ^A [protec
323e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
323f0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c e] object may al
32400 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 ways be used whe
32410 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 re an.** [unprot
32420 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32430 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 lue] object is r
32440 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 equired, so eith
32450 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 er.** kind of [s
32460 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
32470 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 ject can be used
32480 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 with this inter
32490 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 face..**.** If t
324a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
324b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 e called from wi
324c0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 thin the differe
324d0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 nt thread.** tha
324e0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 n the one contai
324f0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 ning the applica
32500 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
32510 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 ction that recei
32520 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ved.** the [sqli
32530 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 te3_context] poi
32540 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 nter, the result
32550 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
32560 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
32570 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
32580 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f lt_blob(sqlite3_
32590 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
325a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
325b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
325c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
325d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
325e0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
325f0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 xt*, double);.SQ
32600 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
32610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32620 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
32630 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
32640 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
32650 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
32660 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 result_error16(s
32670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32680 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
32690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
326a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
326b0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 lt_error_toobig(
326c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
326d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
326e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
326f0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 t_error_nomem(sq
32700 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
32710 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
32720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32730 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 error_code(sqlit
32740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
32750 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
32760 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
32770 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
32780 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 ntext*, int);.SQ
32790 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
327a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
327b0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 64(sqlite3_conte
327c0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 xt*, sqlite3_int
327d0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64);.SQLITE_API
327e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
327f0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
32800 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
32810 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
32820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
32830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32840 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
32850 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
32860 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
32870 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
32880 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ult_text16(sqlit
32890 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
328a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
328b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
328c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
328d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
328e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
328f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
32900 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
32910 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
32920 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
32930 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
32940 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 6be(sqlite3_cont
32950 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
32960 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 *, int,void(*)(v
32970 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
32980 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
32990 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c result_value(sql
329a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 ite3_context*, s
329b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
329c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
329d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
329e0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
329f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 context*, int n)
32a00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
32a10 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f F: Define New Co
32a20 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 llating Sequence
32a30 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 s.**.** ^These f
32a40 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 unctions add, re
32a50 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 move, or modify
32a60 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 a [collation] as
32a70 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
32a80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
32a90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
32aa0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
32ab0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
32ac0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
32ad0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 he collation is
32ae0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a a UTF-8 string.*
32af0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
32b00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
32b10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 and sqlite3_cre
32b20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
32b30 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d ().** and a UTF-
32b40 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
32b50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 ive byte order f
32b60 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
32b70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
32b80 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e .** ^Collation n
32b90 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 ames that compar
32ba0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e e equal accordin
32bb0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 g to [sqlite3_st
32bc0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a rnicmp()] are.**
32bd0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
32be0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e e the same name.
32bf0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 .**.** ^(The thi
32c00 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 rd argument (eTe
32c10 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f xtRep) must be o
32c20 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 ne of the consta
32c30 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 nts:.** <ul>.**
32c40 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
32c50 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8],.** <li> [SQL
32c60 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a ITE_UTF16LE],.**
32c70 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
32c80 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 F16BE],.** <li>
32c90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
32ca0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
32cb0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
32cc0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a ]..** </ul>)^.**
32cd0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 ^The eTextRep a
32ce0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e rgument determin
32cf0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 es the encoding
32d00 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 of strings passe
32d10 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c d.** to the coll
32d20 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
32d30 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 allback, xCallba
32d40 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c ck..** ^The [SQL
32d50 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b ITE_UTF16] and [
32d60 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
32d70 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 GNED] values for
32d80 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 eTextRep.** for
32d90 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 ce strings to be
32da0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 UTF16 with nati
32db0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
32dc0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
32dd0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
32de0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 lue for eTextRep
32df0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 forces strings
32e00 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 to begin.** on a
32e10 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 n even byte addr
32e20 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ess..**.** ^The
32e30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
32e40 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 pArg, is an app
32e50 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
32e60 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 inter that is pa
32e70 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 ssed.** through
32e80 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
32e90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c ument to the col
32ea0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
32eb0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
32ec0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
32ed0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 ent, xCallback,
32ee0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
32ef0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
32f00 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 nction..** ^Mult
32f10 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 iple collating f
32f20 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 unctions can be
32f30 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
32f40 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
32f50 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 ut.** with diffe
32f60 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 rent eTextRep pa
32f70 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c rameters and SQL
32f80 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 ite will use whi
32f90 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 chever.** functi
32fa0 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 on requires the
32fb0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
32fc0 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 data transformat
32fd0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ion..** ^If the
32fe0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 xCallback argume
32ff0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 nt is NULL then
33000 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
33010 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c nction is.** del
33020 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c eted. ^When all
33030 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
33040 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 ions having the
33050 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 same name are de
33060 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 leted,.** that c
33070 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c ollation is no l
33080 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a onger usable..**
33090 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 .** ^The collati
330a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c ng function call
330b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
330c0 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 with a copy of t
330d0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c he pArg .** appl
330e0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
330f0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 nter and with tw
33100 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 o strings in the
33110 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 encoding specif
33120 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 ied.** by the eT
33130 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e extRep argument.
33140 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 The collating
33150 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 function must re
33160 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 turn an.** integ
33170 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 er that is negat
33180 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f ive, zero, or po
33190 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 sitive.** if the
331a0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
331b0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 less than, equa
331c0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
331d0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
331e0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
331f0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 y. A collating
33200 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c function must al
33210 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 ways return the
33220 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 same answer.** g
33230 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e iven the same in
33240 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 puts. If two or
33250 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 more collating
33260 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 functions are re
33270 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 gistered.** to t
33280 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f he same collatio
33290 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 n name (using di
332a0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 fferent eTextRep
332b0 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c values) then al
332c0 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 l.** must give a
332d0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 n equivalent ans
332e0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 wer when invoked
332f0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 with equivalent
33300 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
33310 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
33320 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 ion must obey th
33330 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 e following prop
33340 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a erties for all.*
33350 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 * strings A, B,
33360 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c and C:.**.** <ol
33370 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d >.** <li> If A==
33380 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 B then B==A..**
33390 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 <li> If A==B and
333a0 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e B==C then A==C.
333b0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 .** <li> If A<
333c0 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a ;B THEN B>A..
333d0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
333e0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 B and B<C the
333f0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f n A<C..** </o
33400 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f l>.**.** If a co
33410 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33420 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 fails any of th
33430 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 e above constrai
33440 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 nts and that.**
33450 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
33460 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 on is registere
33470 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e d and used, then
33480 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
33490 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e SQLite.** is un
334a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
334b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 The sqlite3_crea
334c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
334d0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c ) works like sql
334e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
334f0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 ation().** with
33500 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 the addition tha
33510 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 t the xDestroy c
33520 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
33530 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a ed on pArg when.
33540 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 ** the collating
33550 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c function is del
33560 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 eted..** ^Collat
33570 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ing functions ar
33580 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 e deleted when t
33590 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
335a0 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 en by later.** c
335b0 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c alls to the coll
335c0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
335d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e unctions or when
335e0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
335f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
33600 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 closed using [s
33610 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e qlite3_close()].
33620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 .**.** ^The xDes
33630 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 troy callback is
33640 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c <u>not</u> call
33650 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 ed if the .** sq
33660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
33670 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 lation_v2() func
33680 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 tion fails. App
33690 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 lications that i
336a0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
336b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
336c0 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f n_v2() with a no
336d0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 n-NULL xDestroy
336e0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
336f0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 .** check the re
33700 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 turn code and di
33710 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 spose of the app
33720 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
33730 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c inter.** themsel
33740 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 ves rather than
33750 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 expecting SQLite
33760 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 to deal with it
33770 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 for them..** Th
33780 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 is is different
33790 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 from every other
337a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
337b0 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 e. The inconsis
337c0 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 tency .** is unf
337d0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e ortunate but can
337e0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 not be changed w
337f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
33800 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f backwards .** co
33810 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
33820 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 ** See also: [s
33830 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
33840 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b _needed()] and [
33850 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
33860 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a n_needed16()]..*
33870 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
33880 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
33890 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c collation(. sql
338a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
338b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
338c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
338d0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 void *pArg,. i
338e0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
338f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
33900 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
33910 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 id*).);.SQLITE_A
33920 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
33930 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
33940 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 v2(. sqlite3*,
33950 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
33960 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
33970 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
33980 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
33990 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
339a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
339b0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 ,const void*),.
339c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
339d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 (void*).);.SQLIT
339e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
339f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
33a00 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
33a10 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
33a20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
33a30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 extRep, . void
33a40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 *pArg,. int(*xC
33a50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
33a60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
33a70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
33a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33a90 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
33aa0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ded Callbacks.**
33ab0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 .** ^To avoid ha
33ac0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 ving to register
33ad0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 all collation s
33ae0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 equences before
33af0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 a database.** ca
33b00 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e n be used, a sin
33b10 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e gle callback fun
33b20 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
33b30 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 istered with the
33b40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
33b50 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 nnection] to be
33b60 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
33b70 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
33b80 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
33b90 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
33ba0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
33bb0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
33bc0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
33bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
33be0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
33bf0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
33c00 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
33c10 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
33c20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
33c30 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
33c40 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
33c50 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ^If sqlite3_coll
33c60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
33c70 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
33c80 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
33c90 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
33ca0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
33cb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 te order..** ^A
33cc0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 call to either f
33cd0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
33ce0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f the existing co
33cf0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 llation-needed c
33d00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
33d10 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 (When the callba
33d20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
33d30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
33d40 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
33d50 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
33d60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
33d70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
33d80 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
33d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
33da0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
33db0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
33dc0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
33dd0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
33de0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
33df0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
33e00 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
33e10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
33e20 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
33e30 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
33e40 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
33e50 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
33e60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
33e70 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
33e80 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
33e90 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
33ea0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
33eb0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
33ec0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
33ed0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ence.)^.**.** Th
33ee0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
33ef0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 ion should regis
33f00 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 ter the desired
33f10 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a collation using.
33f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
33f30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c te_collation()],
33f40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33f50 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c _collation16()],
33f60 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
33f70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33f80 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 _v2()]..*/.SQLIT
33f90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
33fa0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
33fb0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ed(. sqlite3*,
33fc0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 . void*, . voi
33fd0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
33fe0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
33ff0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b ,const char*).);
34000 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
34010 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
34020 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 n_needed16(. sq
34030 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
34040 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 ,. void(*)(void
34050 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 *,sqlite3*,int e
34060 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f TextRep,const vo
34070 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 id*).);..#ifdef
34080 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 SQLITE_HAS_CODEC
34090 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
340a0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e he key for an en
340b0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 crypted database
340c0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
340d0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c should be.** cal
340e0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 led right after
340f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a sqlite3_open()..
34100 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
34110 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
34120 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
34130 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
34140 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
34150 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c f SQLite..*/.SQL
34160 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
34170 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 te3_key(. sqlit
34180 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
34190 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
341a0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
341b0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
341c0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
341d0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b Key /* The k
341e0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
341f0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f Change the key o
34200 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 n an open databa
34210 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 se. If the curr
34220 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 ent database is
34230 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 not.** encrypted
34240 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 , this routine w
34250 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 ill encrypt it.
34260 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e If pNew==0 or n
34270 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 New==0, the.** d
34280 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 atabase is decry
34290 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 pted..**.** The
342a0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
342b0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
342c0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
342d0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
342e0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
342f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
34300 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 t sqlite3_rekey(
34310 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
34320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
34330 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
34340 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
34350 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
34360 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
34370 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a /* The new key *
34380 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 /.);../*.** Spec
34390 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 ify the activati
343a0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 on key for a SEE
343b0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
343c0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
343d0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 , none of the SE
343e0 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 E routines will
343f0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f work..*/.SQLITE_
34400 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
34410 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 _activate_see(.
34420 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
34430 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 ssPhrase
34440 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 /* Activation ph
34450 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 rase */.);.#endi
34460 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 f..#ifdef SQLITE
34470 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a _ENABLE_CEROD./*
34480 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
34490 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 activation key f
344a0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 or a CEROD datab
344b0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a ase. Unless .**
344c0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 activated, none
344d0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f of the CEROD ro
344e0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b utines will work
344f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
34500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 void sqlite3_act
34510 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 ivate_cerod(. c
34520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 onst char *zPass
34530 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a Phrase /*
34540 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 Activation phra
34550 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a se */.);.#endif.
34560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34570 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 Suspend Executi
34580 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 on For A Short T
34590 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ime.**.** The sq
345a0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 lite3_sleep() fu
345b0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 nction causes th
345c0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 e current thread
345d0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 to suspend exec
345e0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 ution.** for at
345f0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f least a number o
34600 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 f milliseconds s
34610 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 pecified in its
34620 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
34630 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e If the operatin
34640 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f g system does no
34650 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 t support sleep
34660 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a requests with.**
34670 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d millisecond tim
34680 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 e resolution, th
34690 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c en the time will
346a0 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 be rounded up t
346b0 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 o.** the nearest
346c0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d second. The num
346d0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
346e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 nds of sleep act
346f0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 ually.** request
34700 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 ed from the oper
34710 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 ating system is
34720 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
34730 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e ^SQLite implemen
34740 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ts this interfac
34750 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 e by calling the
34760 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 xSleep().** met
34770 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
34780 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
34790 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 object. If the
347a0 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
347b0 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 .** of the defau
347c0 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d lt VFS is not im
347d0 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 plemented correc
347e0 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c tly, or not impl
347f0 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c emented at.** al
34800 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 l, then the beha
34810 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
34820 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 sleep() may devi
34830 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 ate from the des
34840 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 cription.** in t
34850 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
34860 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 graphs..*/.SQLIT
34870 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
34880 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 3_sleep(int);../
34890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
348a0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 ame Of The Folde
348b0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 r Holding Tempor
348c0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 ary Files.**.**
348d0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c ^(If this global
348e0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 variable is mad
348f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 e to point to a
34900 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a string which is.
34910 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
34920 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 folder (a.k.a.
34930 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
34940 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
34950 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
34960 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 by SQLite when u
34970 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
34980 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
34990 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 FS].** will be p
349a0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
349b0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 rectory.)^ ^If
349c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
349d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
349e0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
349f0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
34a00 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
34a10 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
34a20 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
34a30 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
34a40 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
34a50 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
34a60 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
34a70 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
34a80 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
34a90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
34aa0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
34ab0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
34ac0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
34ad0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
34ae0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
34af0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
34b00 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
34b10 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
34b20 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
34b30 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
34b40 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
34b50 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
34b60 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
34b70 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
34b80 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
34b90 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
34ba0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
34bb0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
34bc0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
34bd0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
34be0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 ** ^The [temp_st
34bf0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
34c00 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
34c10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
34c20 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
34c30 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
34c40 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
34c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
34c60 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
34c70 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 .** the [temp_st
34c80 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
34c90 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
34ca0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
34cb0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
34cc0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
34cd0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
34ce0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
34cf0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
34d00 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
34d10 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
34d20 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
34d30 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
34d40 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
34d50 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
34d60 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
34d70 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
34d80 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
34d90 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
34da0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
34db0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
34dc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
34dd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
34de0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
34df0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 of the [temp_st
34e00 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
34e10 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
34e20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
34e30 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c TE_API char *sql
34e40 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
34e50 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ory;../*.** CAPI
34e60 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 3REF: Test For A
34e70 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a uto-Commit Mode.
34e80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 ** KEYWORDS: {au
34e90 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a tocommit mode}.*
34ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34eb0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 3_get_autocommit
34ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
34ed0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 urns non-zero or
34ee0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 .** zero if the
34ef0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 given database c
34f00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 onnection is or
34f10 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f is not in autoco
34f20 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 mmit mode,.** re
34f30 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 spectively. ^Au
34f40 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
34f50 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a on by default..
34f60 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d ** ^Autocommit m
34f70 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 ode is disabled
34f80 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 by a [BEGIN] sta
34f90 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f tement..** ^Auto
34fa0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 commit mode is r
34fb0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b e-enabled by a [
34fc0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c COMMIT] or [ROLL
34fd0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 BACK]..**.** If
34fe0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 certain kinds of
34ff0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e errors occur on
35000 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 a statement wit
35010 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 hin a multi-stat
35020 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 ement.** transac
35030 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 tion (errors inc
35040 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 luding [SQLITE_F
35050 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f ULL], [SQLITE_IO
35060 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ERR],.** [SQLITE
35070 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 _NOMEM], [SQLITE
35080 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c _BUSY], and [SQL
35090 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 ITE_INTERRUPT])
350a0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e then the.** tran
350b0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 saction might be
350c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
350d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 omatically. The
350e0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 only way to.**
350f0 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 find out whether
35100 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 SQLite automati
35110 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
35120 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
35130 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 n after.** an er
35140 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 ror is to use th
35150 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a is function..**.
35160 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 ** If another th
35170 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 read changes the
35180 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 autocommit stat
35190 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 us of the databa
351a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
351b0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 while this rout
351c0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 ine is running,
351d0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 then the return
351e0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 value.** is unde
351f0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
35200 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
35210 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 _get_autocommit(
35220 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
35230 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 * CAPI3REF: Find
35240 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 The Database Ha
35250 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 ndle Of A Prepar
35260 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a ed Statement.**.
35270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35280 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 db_handle interf
35290 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
352a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
352b0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
352c0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 to which a [prep
352d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
352e0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b belongs. ^The [
352f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35300 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ion].** returned
35310 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 by sqlite3_db_h
35320 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d andle is the sam
35330 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
35340 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 ection].** that
35350 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 was the first ar
35360 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 gument.** to the
35370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
35380 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 e_v2()] call (or
35390 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 its variants) t
353a0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a hat was used to.
353b0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 ** create the st
353c0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 atement in the f
353d0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 irst place..*/.S
353e0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
353f0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
35400 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
35410 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
35420 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 3REF: Find the n
35430 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ext prepared sta
35440 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 tement.**.** ^Th
35450 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
35460 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
35470 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 o the next [prep
35480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
35490 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 after.** pStmt a
354a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
354b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
354c0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e nection] pDb. ^
354d0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c If pStmt is NULL
354e0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e .** then this in
354f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
35500 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
35510 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 first prepared
35520 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 statement.** ass
35530 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
35540 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
35550 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e tion pDb. ^If n
35560 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 o prepared state
35570 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 ment.** satisfie
35580 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 s the conditions
35590 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
355a0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c , it returns NUL
355b0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 L..**.** The [da
355c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
355d0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 n] pointer D in
355e0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
355f0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
35600 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 D,S)] must refer
35610 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 to an open data
35620 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
35630 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 on and in partic
35640 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 ular must not be
35650 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
35660 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 .*/.SQLITE_API s
35670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c qlite3_stmt *sql
35680 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 ite3_next_stmt(s
35690 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c qlite3 *pDb, sql
356a0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
356b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
356c0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 EF: Commit And R
356d0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 ollback Notifica
356e0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
356f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35700 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 3_commit_hook()
35710 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
35720 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a ers a callback.*
35730 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 * function to be
35740 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
35750 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
35760 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d is [COMMIT | com
35770 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 mitted]..** ^Any
35780 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
35790 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
357a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
357b0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
357c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
357d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
357e0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
357f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c ^The sqlite3_rol
35800 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 lback_hook() int
35810 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
35820 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
35830 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
35840 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
35850 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
35860 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c [ROLLBACK | roll
35870 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e ed back]..** ^An
35880 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
35890 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
358a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c l to sqlite3_rol
358b0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 lback_hook().**
358c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
358d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
358e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
358f0 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 ** ^The pArg arg
35900 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 ument is passed
35910 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 through to the c
35920 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 allback..** ^If
35930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
35940 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
35950 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e nction returns n
35960 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e on-zero,.** then
35970 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 the commit is c
35980 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
35990 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
359a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d ^The sqlite3_com
359b0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 mit_hook(D,C,P)
359c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c and sqlite3_roll
359d0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 back_hook(D,C,P)
359e0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 functions.** re
359f0 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d turn the P argum
35a00 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 ent from the pre
35a10 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 vious call of th
35a20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a e same function.
35a30 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b ** on the same [
35a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35a50 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 ion] D, or NULL
35a60 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 for.** the first
35a70 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 call for each f
35a80 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a unction on D..**
35a90 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
35aa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35ab0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
35ac0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
35ad0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
35ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35af0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
35b00 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 e callback. Any
35b10 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d actions.** to m
35b20 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 odify the databa
35b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
35b40 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 st be deferred u
35b50 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a ntil after the.*
35b60 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 * completion of
35b70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
35b80 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 p()] call that t
35b90 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d riggered the com
35ba0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 mit.** or rollba
35bb0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 ck hook in the f
35bc0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e irst place..** N
35bd0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
35be0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
35bf0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
35c00 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
35c10 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
35c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
35c30 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
35c40 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
35c50 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
35c60 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 .** ^Registering
35c70 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e a NULL function
35c80 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 disables the ca
35c90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 llback..**.** ^W
35ca0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 hen the commit h
35cb0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 ook callback rou
35cc0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 tine returns zer
35cd0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a o, the [COMMIT].
35ce0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 ** operation is
35cf0 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 allowed to conti
35d00 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e nue normally. ^
35d10 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f If the commit ho
35d20 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f ok.** returns no
35d30 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 n-zero, then the
35d40 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e [COMMIT] is con
35d50 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 verted into a [R
35d60 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 OLLBACK]..** ^Th
35d70 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 e rollback hook
35d80 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 is invoked on a
35d90 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 rollback that re
35da0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d sults from a com
35db0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 mit.** hook retu
35dc0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 rning non-zero,
35dd0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 just as it would
35de0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 be with any oth
35df0 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a er rollback..**.
35e00 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 ** ^For the purp
35e10 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 oses of this API
35e20 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 , a transaction
35e30 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 is said to have
35e40 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 been.** rolled b
35e50 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 ack if an explic
35e60 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 it "ROLLBACK" st
35e70 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 atement is execu
35e80 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 ted, or.** an er
35e90 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e ror or constrain
35ea0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c t causes an impl
35eb0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f icit rollback to
35ec0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 occur..** ^The
35ed0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 rollback callbac
35ee0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
35ef0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f if a transactio
35f00 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 n is.** automati
35f10 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
35f20 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 k because the da
35f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35f40 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
35f50 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
35f60 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f [sqlite3_update_
35f70 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 hook()] interfac
35f80 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
35f90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
35fa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
35fb0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
35fc0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 *), void*);.SQLI
35fd0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
35fe0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
35ff0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ok(sqlite3*, voi
36000 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f d(*)(void *), vo
36010 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
36020 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e I3REF: Data Chan
36030 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ge Notification
36040 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
36050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 ^The sqlite3_upd
36060 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 ate_hook() inter
36070 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
36080 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
36090 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
360a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
360b0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 ion] identified
360c0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
360d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 ument.** to be i
360e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
360f0 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 a row is updated
36100 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
36110 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 leted..** ^Any c
36120 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
36130 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
36140 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a o this function.
36150 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
36160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
36170 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
36180 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 n..**.** ^The se
36190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
361a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
361b0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
361c0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
361d0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
361e0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
361f0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 ed..** ^The firs
36200 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
36210 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 e callback is a
36220 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
36230 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f d argument.** to
36240 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
36250 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 hook()..** ^The
36260 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 second callback
36270 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
36280 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 of [SQLITE_INSER
36290 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 T], [SQLITE_DELE
362a0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 TE],.** or [SQLI
362b0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 TE_UPDATE], depe
362c0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 nding on the ope
362d0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 ration that caus
362e0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a ed the callback.
362f0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
36300 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 ..** ^The third
36310 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d and fourth argum
36320 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ents to the call
36330 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 back contain poi
36340 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 nters to the.**
36350 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 database and tab
36360 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 le name containi
36370 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 ng the affected
36380 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e row..** ^The fin
36390 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 al callback para
363a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f meter is the [ro
363b0 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e wid] of the row.
363c0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 .** ^In the case
363d0 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 of an update, t
363e0 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 his is the [rowi
363f0 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 d] after the upd
36400 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e ate takes place.
36410 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 .**.** ^(The upd
36420 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 ate hook is not
36430 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 invoked when int
36440 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 ernal system tab
36450 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 les are.** modif
36460 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 ied (i.e. sqlite
36470 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 _master and sqli
36480 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a te_sequence).)^.
36490 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 **.** ^In the cu
364a0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 rrent implementa
364b0 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 tion, the update
364c0 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 hook.** is not
364d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 invoked when dup
364e0 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 lication rows ar
364f0 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 e deleted becaus
36500 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 e of an.** [ON C
36510 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e ONFLICT | ON CON
36520 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 FLICT REPLACE] c
36530 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 lause. ^Nor is
36540 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a the update hook.
36550 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ** invoked when
36560 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 rows are deleted
36570 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e using the [trun
36580 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f cate optimizatio
36590 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 n]..** The excep
365a0 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e tions defined in
365b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 this paragraph
365c0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 might change in
365d0 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 a future.** rele
365e0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ase of SQLite..*
365f0 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 *.** The update
36600 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 hook implementat
36610 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
36620 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
36630 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
36640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
36650 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
36660 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f d the update hoo
36670 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a k. Any actions.
36680 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 ** to modify the
36690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
366a0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 tion must be def
366b0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 erred until afte
366c0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 r the.** complet
366d0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
366e0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
366f0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
36700 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e the update hook.
36710 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
36720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
36730 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
36740 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
36750 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
36760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36770 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
36780 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
36790 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
367a0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 h..**.** ^The sq
367b0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
367c0 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f k(D,C,P) functio
367d0 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 n.** returns the
367e0 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d P argument from
367f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
36800 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d ll.** on the sam
36810 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
36820 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 ection] D, or NU
36830 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 LL for.** the fi
36840 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a rst call on D..*
36850 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
36860 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 e [sqlite3_commi
36870 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 t_hook()] and [s
36880 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
36890 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 hook()].** inter
368a0 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 faces..*/.SQLITE
368b0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
368c0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a e3_update_hook(.
368d0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
368e0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e oid(*)(void *,in
368f0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c t ,char const *,
36900 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c char const *,sql
36910 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 ite3_int64),. v
36920 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 oid*.);../*.** C
36930 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
36940 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 Or Disable Share
36950 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a d Pager Cache.**
36960 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 KEYWORDS: {shar
36970 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 ed cache}.**.**
36980 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 ^(This routine e
36990 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
369a0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
369b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
369c0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
369d0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
369e0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
369f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
36a00 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
36a10 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
36a20 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
36a30 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
36a40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
36a50 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
36a60 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
36a70 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a nt is false.)^.*
36a80 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 *.** ^Cache shar
36a90 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 ing is enabled a
36aa0 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 nd disabled for
36ab0 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 an entire proces
36ac0 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 s..** This is a
36ad0 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c change as of SQL
36ae0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
36af0 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 0. In prior vers
36b00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a ions of SQLite,.
36b10 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 ** sharing was e
36b20 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
36b30 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 ed for each thre
36b40 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a ad separately..*
36b50 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 *.** ^(The cache
36b60 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 sharing mode se
36b70 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 t by this interf
36b80 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 ace effects all
36b90 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 subsequent.** ca
36ba0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
36bb0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
36bc0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
36bd0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 d [sqlite3_open1
36be0 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 6()]..** Existin
36bf0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 g database conne
36c00 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
36c10 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 use the sharing
36c20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 mode.** that was
36c30 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 in effect at th
36c40 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 e time they were
36c50 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a opened.)^.**.**
36c60 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
36c70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
36c80 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 OK] if shared ca
36c90 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 che was enabled
36ca0 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 or disabled.** s
36cb0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e uccessfully. An
36cc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
36cd0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 returned otherw
36ce0 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 ise.)^.**.** ^Sh
36cf0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 ared cache is di
36d00 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
36d10 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 t. But this migh
36d20 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 t change in.** f
36d30 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
36d40 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 f SQLite. Appli
36d50 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 cations that car
36d60 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a e about shared.*
36d70 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 * cache setting
36d80 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 should set it ex
36d90 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 plicitly..**.**
36da0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 See Also: [SQLi
36db0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 te Shared-Cache
36dc0 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f Mode].*/.SQLITE_
36dd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
36de0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
36df0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a che(int);../*.**
36e00 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d CAPI3REF: Attem
36e10 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 pt To Free Heap
36e20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 Memory.**.** ^Th
36e30 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 e sqlite3_releas
36e40 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 e_memory() inter
36e50 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
36e60 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a free N bytes.**
36e70 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 of heap memory
36e80 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 by deallocating
36e90 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 non-essential me
36ea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
36eb0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 .** held by the
36ec0 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 database library
36ed0 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 . Memory used
36ee0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
36ef0 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d e.** pages to im
36f00 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
36f10 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 e is an example
36f20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c of non-essential
36f30 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c memory..** ^sql
36f40 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
36f50 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 ory() returns th
36f60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
36f70 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 s actually freed
36f80 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 ,.** which might
36f90 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
36fa0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 than the amount
36fb0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e requested..** ^
36fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 The sqlite3_rele
36fd0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 ase_memory() rou
36fe0 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 tine is a no-op
36ff0 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a returning zero.*
37000 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e * if SQLite is n
37010 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ot compiled with
37020 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
37030 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
37040 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 T]..*/.SQLITE_AP
37050 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 I int sqlite3_re
37060 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 lease_memory(int
37070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
37080 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d EF: Impose A Lim
37090 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a it On Heap Size.
370a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
370b0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
370c0 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 it64() interface
370d0 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 sets and/or que
370e0 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 ries the.** soft
370f0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d limit on the am
37100 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d ount of heap mem
37110 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 ory that may be
37120 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
37130 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ite..** ^SQLite
37140 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 strives to keep
37150 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c heap memory util
37160 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 ization below th
37170 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c e soft heap.** l
37180 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 imit by reducing
37190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
371a0 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 ages held in the
371b0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 page cache.** a
371c0 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 s heap memory us
371d0 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 ages approaches
371e0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 the limit..** ^T
371f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
37200 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 it is "soft" bec
37210 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 ause even though
37220 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 SQLite strives
37230 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 to stay.** below
37240 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 the limit, it w
37250 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c ill exceed the l
37260 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e imit rather than
37270 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 generate.** an
37280 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 [SQLITE_NOMEM] e
37290 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 rror. In other
372a0 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 words, the soft
372b0 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 heap limit .** i
372c0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e s advisory only.
372d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
372e0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
372f0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
37300 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 limit64() is the
37310 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 size of.** the
37320 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
37330 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c prior to the cal
37340 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 l. ^If the argu
37350 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 ment N is negati
37360 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 ve.** then no ch
37370 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 ange is made to
37380 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
37390 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 mit. Hence, the
373a0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 current.** size
373b0 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 of the soft hea
373c0 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 p limit can be d
373d0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 etermined by inv
373e0 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 oking.** sqlite3
373f0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
37400 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 64() with a nega
37410 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a tive argument..*
37420 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 *.** ^If the arg
37430 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 ument N is zero
37440 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 then the soft he
37450 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 ap limit is disa
37460 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 bled..**.** ^(Th
37470 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
37480 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 t is not enforce
37490 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 d in the current
374a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
374b0 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 ** if one or mor
374c0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 e of following c
374d0 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 onditions are tr
374e0 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ue:.**.** <ul>.*
374f0 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 * <li> The soft
37500 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 heap limit is se
37510 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c t to zero..** <l
37520 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e i> Memory accoun
37530 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 ting is disabled
37540 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 using a combina
37550 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 tion of the.**
37560 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e [sqlite3_con
37570 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
37580 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e FIG_MEMSTATUS],.
37590 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f ..) start-time o
375a0 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 ption and.**
375b0 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 the [SQLITE_DE
375c0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d FAULT_MEMSTATUS]
375d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
375e0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e tion..** <li> An
375f0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 alternative pag
37600 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
37610 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 tation is specif
37620 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 ied using.**
37630 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 [sqlite3_confi
37640 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
37650 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a G_PCACHE],...)..
37660 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 ** <li> The page
37670 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 cache allocates
37680 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 from its own me
37690 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 mory pool suppli
376a0 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 ed.** by [s
376b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
376c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
376d0 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 GECACHE],...) ra
376e0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 ther than.**
376f0 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e from the heap.
37700 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
37710 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 * Beginning with
37720 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
37730 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 3.7.3, the soft
37740 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e heap limit is en
37750 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 forced.** regard
37760 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
37770 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 or not the [SQLI
37780 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 TE_ENABLE_MEMORY
37790 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 _MANAGEMENT].**
377a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
377b0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ion is invoked.
377c0 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e With [SQLITE_EN
377d0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
377e0 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 GEMENT],.** the
377f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
37800 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 is enforced on e
37810 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
37820 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 cation. Without
37830 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
37840 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 LE_MEMORY_MANAGE
37850 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 MENT], the soft
37860 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e heap limit is on
37870 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 ly enforced.** w
37880 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c hen memory is al
37890 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 located by the p
378a0 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 age cache. Test
378b0 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 ing suggests tha
378c0 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 t because.** the
378d0 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 page cache is t
378e0 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d he predominate m
378f0 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 emory user in SQ
37900 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 Lite, most.** ap
37910 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 plications will
37920 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 achieve adequate
37930 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
37940 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 enforcement wit
37950 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 hout.** the use
37960 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c of [SQLITE_ENABL
37970 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d E_MEMORY_MANAGEM
37980 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENT]..**.** The
37990 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e circumstances un
379a0 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 der which SQLite
379b0 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 will enforce th
379c0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
379d0 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 t may.** changes
379e0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
379f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
37a00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
37a10 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
37a20 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
37a30 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 it64(sqlite3_int
37a40 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 64 N);../*.** CA
37a50 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
37a60 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d ed Soft Heap Lim
37a70 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 it Interface.**
37a80 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
37a90 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 This is a depre
37aa0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 cated version of
37ab0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f the [sqlite3_so
37ac0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
37ad0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
37ae0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 This routine i
37af0 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 s provided for h
37b00 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
37b10 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e ibility.** only.
37b20 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 All new applic
37b30 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 ations should us
37b40 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
37b50 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
37b60 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 t64()] interface
37b70 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 rather than thi
37b80 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 s one..*/.SQLITE
37b90 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
37ba0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 ECATED void sqli
37bb0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
37bc0 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a mit(int N);.../*
37bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
37be0 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 tract Metadata A
37bf0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 bout A Column Of
37c00 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e A Table.**.** ^
37c10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
37c20 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 urns metadata ab
37c30 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 out a specific c
37c40 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 olumn of a speci
37c50 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 fic.** database
37c60 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 table accessible
37c70 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 using the [data
37c80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37c90 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 handle.** passe
37ca0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 d as the first f
37cb0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
37cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c ..**.** ^The col
37cd0 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 umn is identifie
37ce0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c d by the second,
37cf0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
37d00 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a h parameters to.
37d10 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
37d20 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
37d30 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 rameter is eithe
37d40 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 r the name of th
37d50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 e database.** (i
37d60 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d .e. "main", "tem
37d70 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 p", or an attach
37d80 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e ed database) con
37d90 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 taining the spec
37da0 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f ified.** table o
37db0 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 r NULL. ^If it i
37dc0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c s NULL, then all
37dd0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
37de0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 ses are searched
37df0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c .** for the tabl
37e00 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
37e10 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 algorithm used
37e20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 by the database
37e30 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 engine to.** res
37e40 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 olve unqualified
37e50 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 table reference
37e60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 s..**.** ^The th
37e70 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
37e80 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
37e90 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 s function are t
37ea0 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c he table and col
37eb0 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 umn.** name of t
37ec0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d he desired colum
37ed0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
37ee0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 Neither of thes
37ef0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 e parameters.**
37f00 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a may be NULL..**.
37f10 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 ** ^Metadata is
37f20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 returned by writ
37f30 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ing to the memor
37f40 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 y locations pass
37f50 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a ed as the 5th.**
37f60 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
37f70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
37f80 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e is function. ^An
37f90 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d y of these argum
37fa0 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e ents may be.** N
37fb0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 ULL, in which ca
37fc0 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e se the correspon
37fd0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 ding element of
37fe0 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 metadata is omit
37ff0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c ted..**.** ^(<bl
38000 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
38010 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
38020 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 ** <tr><th> Para
38030 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 meter <th> Outpu
38040 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 t<br>Type <th>
38050 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a Description.**.*
38060 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c * <tr><td> 5th <
38070 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
38080 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a <td> Data type.*
38090 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c * <tr><td> 6th <
380a0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
380b0 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 <td> Name of def
380c0 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ault collation s
380d0 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c equence.** <tr><
380e0 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 td> 7th <td> int
380f0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 <td> Tr
38100 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 ue if column has
38110 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 a NOT NULL cons
38120 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 traint.** <tr><t
38130 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 8th <td> int
38140 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
38150 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 e if column is p
38160 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 art of the PRIMA
38170 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 RY KEY.** <tr><t
38180 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 9th <td> int
38190 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
381a0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b e if column is [
381b0 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a AUTOINCREMENT].*
381c0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
381d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
381e0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
381f0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
38200 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e e character poin
38210 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f ters returned fo
38220 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 r the.** declara
38230 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f tion type and co
38240 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
38250 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 is valid only u
38260 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a ntil the next.**
38270 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c call to any SQL
38280 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e ite API function
38290 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
382a0 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 specified table
382b0 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 is actually a vi
382c0 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ew, an [error co
382d0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
382e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 .**.** ^If the s
382f0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 pecified column
38300 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 is "rowid", "oid
38310 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 " or "_rowid_" a
38320 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 nd an.** [INTEGE
38330 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 R PRIMARY KEY] c
38340 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 olumn has been e
38350 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
38360 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 ed, then the out
38370 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
38380 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
38390 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
383a0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 lared column. ^(
383b0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a If there is no.*
383c0 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 * explicitly dec
383d0 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 lared [INTEGER P
383e0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 RIMARY KEY] colu
383f0 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 mn, then the out
38400 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
38410 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c s are set as fol
38420 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 lows:.**.** <pre
38430 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 >.** data ty
38440 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a pe: "INTEGER".**
38450 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 collation s
38460 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 equence: "BINARY
38470 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c ".** not nul
38480 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d l: 0.** prim
38490 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 ary key: 1.**
384a0 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 auto increment
384b0 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a : 0.** </pre>)^.
384c0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e **.** ^(This fun
384d0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f ction may load o
384e0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d ne or more schem
384f0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 as from database
38500 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a files. If an.**
38510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
38520 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 ring this proces
38530 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 s, or if the req
38540 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 uested table or
38550 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 column.** cannot
38560 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 be found, an [e
38570 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
38580 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 turned and an er
38590 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 ror message left
385a0 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 .** in the [data
385b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
385c0 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 (to be retrieve
385d0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f d using sqlite3_
385e0 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a errmsg()).)^.**.
385f0 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 ** ^This API is
38600 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
38610 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 f the library wa
38620 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
38630 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
38640 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 NABLE_COLUMN_MET
38650 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 ADATA] C-preproc
38660 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 essor symbol def
38670 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ined..*/.SQLITE_
38680 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38690 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
386a0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 adata(. sqlite3
386b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
386c0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 /* Connecti
386d0 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 on handle */. c
386e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
386f0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 me, /* Da
38700 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e tabase name or N
38710 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ULL */. const c
38720 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c har *zTableName,
38730 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 /* Table na
38740 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 me */. const ch
38750 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c ar *zColumnName,
38760 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 /* Column na
38770 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e me */. char con
38780 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c st **pzDataType,
38790 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 /* OUTPUT: D
387a0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 eclared data typ
387b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
387c0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 t **pzCollSeq,
387d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f /* OUTPUT: Co
387e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
387f0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a name */. int *
38800 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 pNotNull,
38810 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54