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 38 2e 34 2e 33 2e 20 ersion 3.8.4.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 54 mit LFS..**.** T
0b00: 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
0b10: 67 72 61 70 68 20 77 61 73 20 77 72 69 74 74 65 graph was writte
0b20: 6e 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 n in 2005. (Thi
0b30: 73 20 70 61 72 61 67 72 61 70 68 20 69 73 20 77 s paragraph is w
0b40: 72 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 ritten.** on 200
0b50: 38 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 8-11-28.) These
0b60: 64 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 days, all Linux
0b70: 6b 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 kernels support
0b80: 6c 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a large files, so.
0b90: 2a 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 ** you should pr
0ba0: 6f 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 obably leave LFS
0bb0: 20 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 enabled. But s
0bc0: 6f 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 ome embedded pla
0bd0: 74 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 tforms might.**
0be0: 6c 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 lack LFS in whic
0bf0: 68 20 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 h case the SQLIT
0c00: 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 E_DISABLE_LFS ma
0c10: 63 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 cro might still
0c20: 62 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a be useful..**.**
0c30: 20 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 Similar is true
0c40: 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 for Mac OS X.
0c50: 4c 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 LFS is only supp
0c60: 6f 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 orted on Mac OS
0c70: 58 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a X 9 and later..*
0c80: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
0c90: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 _DISABLE_LFS.# d
0ca0: 65 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c efine _LARGE_FIL
0cb0: 45 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 E 1.# ifnd
0cc0: 65 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f ef _FILE_OFFSET_
0cd0: 42 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 BITS.# define
0ce0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 _FILE_OFFSET_BIT
0cf0: 53 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 S 64.# endif.# d
0d00: 65 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 efine _LARGEFILE
0d10: 5f 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 _SOURCE 1.#endif
0d20: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 ../*.** For MinG
0d30: 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 W, check to see
0d40: 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64 if we can includ
0d50: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c e the header fil
0d60: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73 e containing its
0d70: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f .** version info
0d80: 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f rmation, among o
0d90: 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f ther things. No
0da0: 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74 rmally, this int
0db0: 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 ernal MinGW.** h
0dc0: 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64 eader file would
0dd0: 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75 [only] be inclu
0de0: 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ded automaticall
0df0: 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57 y by other MinGW
0e00: 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73 header.** files
0e10: 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63 ; however, the c
0e20: 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e ontained version
0e30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
0e40: 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79 20 now required by
0e50: 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66 this.** header f
0e60: 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 ile to work arou
0e70: 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 nd binary compat
0e80: 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20 28 ibility issues (
0e90: 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a see below) and.*
0ea0: 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e * this is the on
0eb0: 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20 ly known way to
0ec0: 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20 reliably obtain
0ed0: 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65 it. This entire
0ee0: 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f #if block.** wo
0ef0: 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c uld be completel
0f00: 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66 y unnecessary if
0f10: 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f there was any o
0f20: 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74 65 ther way of dete
0f30: 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 cting.** MinGW v
0f40: 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f 63 ia their preproc
0f50: 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74 essor (e.g. if t
0f60: 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74 hey customized t
0f70: 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66 69 heir GCC to defi
0f80: 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 ne.** some MinGW
0f90: 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73 -specific macros
0fa0: 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69 ). When compili
0fb0: 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69 ng for MinGW, ei
0fc0: 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56 ther the.** _HAV
0fd0: 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41 E_MINGW_H or _HA
0fe0: 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 VE__MINGW_H (not
0ff0: 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64 65 e the extra unde
1000: 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75 rscore) macro mu
1010: 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64 st be.** defined
1020: 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74 ; otherwise, det
1030: 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 ection of condit
1040: 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f ions specific to
1050: 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a MinGW will be.*
1060: 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 * disabled..*/.#
1070: 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 if defined(_HAVE
1080: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c _MINGW_H).# incl
1090: 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65 ude "mingw.h".#e
10a0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 lif defined(_HAV
10b0: 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e E__MINGW_H).# in
10c0: 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22 clude "_mingw.h"
10d0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 .#endif../*.** F
10e0: 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e or MinGW version
10f0: 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72 4.x (and higher
1100: 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 ), check to see
1110: 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 if the _USE_32BI
1120: 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 T_TIME_T.** defi
1130: 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20 74 ne is required t
1140: 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72 o maintain binar
1150: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 y compatibility
1160: 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72 75 with the MSVC ru
1170: 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79 ntime.** library
1180: 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f in use (e.g. fo
1190: 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a r Windows XP)..*
11a0: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f /.#if !defined(_
11b0: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 USE_32BIT_TIME_T
11c0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55 ) && !defined(_U
11d0: 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29 SE_64BIT_TIME_T)
11e0: 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 && \. define
11f0: 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65 d(_WIN32) && !de
1200: 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26 fined(_WIN64) &&
1210: 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f \. defined(_
1220: 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 _MINGW_MAJOR_VER
1230: 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57 SION) && __MINGW
1240: 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e _MAJOR_VERSION >
1250: 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66 = 4 && \. def
1260: 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 ined(__MSVCRT__)
1270: 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33 .# define _USE_3
1280: 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 2BIT_TIME_T.#end
1290: 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69 if../* The publi
12a0: 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 c SQLite interfa
12b0: 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f ce. The _FILE_O
12c0: 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f FFSET_BITS macro
12d0: 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20 must appear.**
12e0: 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41 first in QNX. A
12f0: 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32 lso, the _USE_32
1300: 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f BIT_TIME_T macro
1310: 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69 72 must appear fir
1320: 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e st for.** MinGW.
1330: 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
1340: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 *** Include sqli
1350: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 te3.h in the mid
1360: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 dle of sqliteInt
1370: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
1380: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
1390: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 *** Begin file s
13a0: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a qlite3.h *******
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
13c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
13d0: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 **/./*.** 2001 S
13e0: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a eptember 15.**.*
13f0: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 * The author dis
1400: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 claims copyright
1410: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 to this source
1420: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 code. In place
1430: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f of.** a legal no
1440: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 tice, here is a
1450: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 blessing:.**.**
1460: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f May you do go
1470: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e od and not evil.
1480: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 .** May you f
1490: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 ind forgiveness
14a0: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 for yourself and
14b0: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e forgive others.
14c0: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 .** May you s
14d0: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 hare freely, nev
14e0: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 er taking more t
14f0: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a han you give..**
1500: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .***************
1510: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1520: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1530: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1540: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 **********.** Th
1550: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 is header file d
1560: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
1570: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51 face that the SQ
1580: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 Lite library.**
1590: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 presents to clie
15a0: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 nt programs. If
15b0: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 a C-function, s
15c0: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 tructure, dataty
15d0: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 pe,.** or consta
15e0: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f nt definition do
15f0: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e es not appear in
1600: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e this file, then
1610: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 it is.** not a
1620: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 published API of
1630: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a SQLite, is subj
1640: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
1650: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c thout.** notice,
1660: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 and should not
1670: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 be referenced by
1680: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 programs that u
1690: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a se SQLite..**.**
16a0: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 Some of the def
16b0: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 initions that ar
16c0: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 e in this file a
16d0: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 re marked as.**
16e0: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 "experimental".
16f0: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e Experimental in
1700: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 terfaces are nor
1710: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 mally new.** fea
1720: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 tures recently a
1730: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 dded to SQLite.
1740: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 We do not antic
1750: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a ipate changes.**
1760: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c to experimental
1770: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 interfaces but
1780: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68 reserve the righ
1790: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 t to make minor
17a0: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 changes.** if ex
17b0: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 perience from us
17c0: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 e "in the wild"
17d0: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61 suggest such cha
17e0: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 nges are prudent
17f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 ..**.** The offi
1800: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 cial C-language
1810: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f API documentatio
1820: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 n for SQLite is
1830: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 derived.** from
1840: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 comments in this
1850: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c file. This fil
1860: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 e is the authori
1870: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a tative source.**
1880: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 on how SQLite i
1890: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75 nterfaces are su
18a0: 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 ppose to operate
18b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 ..**.** The name
18c0: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e of this file un
18d0: 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f der configuratio
18e0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 n management is
18f0: 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a "sqlite.h.in"..*
1900: 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d * The makefile m
1910: 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 akes some minor
1920: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 changes to this
1930: 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e file (such as in
1940: 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 serting.** the v
1950: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 ersion number) a
1960: 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e nd changes its n
1970: 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e ame to "sqlite3.
1980: 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 h" as.** part of
1990: 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 the build proce
19a0: 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f ss..*/.#ifndef _
19b0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 SQLITE3_H_.#defi
19c0: 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 ne _SQLITE3_H_.#
19d0: 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e include <stdarg.
19e0: 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 h> /* Needed
19f0: 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 for the definit
1a00: 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a ion of va_list *
1a10: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 /../*.** Make su
1a20: 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 re we can call t
1a30: 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 his stuff from C
1a40: 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 ++..*/.#if 0.ext
1a50: 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 ern "C" {.#endif
1a60: 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 .../*.** Add the
1a70: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 ability to over
1a80: 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f ride 'extern'.*/
1a90: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
1aa0: 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 EXTERN.# define
1ab0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 SQLITE_EXTERN ex
1ac0: 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66 tern.#endif..#if
1ad0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a ndef SQLITE_API.
1ae0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
1af0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a API.#endif.../*.
1b00: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d ** These no-op m
1b10: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 acros are used i
1b20: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 n front of inter
1b30: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 faces to mark th
1b40: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ose.** interface
1b50: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72 s as either depr
1b60: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 ecated or experi
1b70: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 mental. New app
1b80: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
1b90: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 uld not use depr
1ba0: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 ecated interface
1bb0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
1bc0: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 port for backwar
1bd0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
1be0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
1bf0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
1c00: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
1c10: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
1c20: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
1c30: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
1c40: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
1c50: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
1c60: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
1c70: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
1c80: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
1c90: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
1ca0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
1cb0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
1cc0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
1cd0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
1ce0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
1cf0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
1d00: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
1d10: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
1d20: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
1d30: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
1d40: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
1d50: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
1d60: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
1d70: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
1d80: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
1d90: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
1da0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
1db0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
1dc0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
1dd0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
1de0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
1df0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
1e00: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
1e10: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
1e20: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
1e30: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
1e40: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
1e50: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
1e60: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
1e70: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
1e80: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
1e90: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
1ea0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
1eb0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
1ec0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
1ed0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
1ee0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
1ef0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
1f00: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
1f10: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
1f20: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1f30: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
1f40: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
1f50: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
1f60: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
1f70: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
1f80: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
1f90: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
1fa0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
1fb0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
1fc0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
1fd0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
1fe0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
1ff0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
2000: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
2010: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
2020: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
2030: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
2040: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
2050: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
2060: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
2070: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
2080: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
2090: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
20a0: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
20b0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
20c0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
20d0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
20e0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
20f0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
2100: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
2110: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
2120: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
2130: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
2140: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
2150: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
2160: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
2170: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
2180: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
2190: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
21a0: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
21b0: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
21c0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
21d0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
21e0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
21f0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
2200: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
2210: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
2220: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
2230: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
2240: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
2250: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
2260: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
2270: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
2280: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
2290: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
22a0: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
22b0: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
22c0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
22d0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
22e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
22f0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
2300: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
2310: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
2320: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
2330: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
2340: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
2350: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
2360: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
2370: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
2380: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
2390: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
23a0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
23b0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
23c0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
23d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
23e0: 20 20 20 20 20 22 33 2e 38 2e 34 2e 33 22 0a 23 "3.8.4.3".#
23f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
2400: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 RSION_NUMBER 300
2410: 38 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 8004.#define SQL
2420: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 ITE_SOURCE_ID
2430: 20 20 20 22 32 30 31 34 2d 30 34 2d 30 33 20 31 "2014-04-03 1
2440: 36 3a 35 33 3a 31 32 20 61 36 31 31 66 61 39 36 6:53:12 a611fa96
2450: 63 34 61 38 34 38 36 31 34 65 66 65 38 39 39 31 c4a848614efe8991
2460: 33 30 33 35 39 63 39 66 36 66 62 38 38 39 63 33 30359c9f6fb889c3
2470: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 "../*.** CAPI3RE
2480: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
2490: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
24a0: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ers.** KEYWORDS:
24b0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
24c0: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 , sqlite3_source
24d0: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 id.**.** These i
24e0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 nterfaces provid
24f0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
2500: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
2510: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a QLITE_VERSION],.
2520: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
2530: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 ON_NUMBER], and
2540: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 [SQLITE_SOURCE_I
2550: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f D] C preprocesso
2560: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 r macros.** but
2570: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 are associated w
2580: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 ith the library
2590: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 instead of the h
25a0: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 eader file. ^(C
25b0: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 autious.** progr
25c0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 ammers might inc
25d0: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 lude assert() st
25e0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 atements in thei
25f0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f r application to
2600: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 .** verify that
2610: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
2620: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 by these interfa
2630: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 ces match the ma
2640: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 cros in.** the h
2650: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 eader, and thus
2660: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
2670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a application is.*
2680: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
2690: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 matching library
26a0: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 and header file
26b0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s..**.** <blockq
26c0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 uote><pre>.** as
26d0: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 sert( sqlite3_li
26e0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
26f0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f )==SQLITE_VERSIO
2700: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 N_NUMBER );.** a
2710: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
2720: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
2730: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 ,SQLITE_SOURCE_I
2740: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 D)==0 );.** asse
2750: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 rt( strcmp(sqlit
2760: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c e3_libversion(),
2770: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d SQLITE_VERSION)=
2780: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c =0 );.** </pre><
2790: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
27a0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
27b0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
27c0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 ng constant cont
27d0: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 ains the text of
27e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
27f0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 ].** macro. ^Th
2800: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
2810: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 sion() function
2820: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2830: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 r to the.** to t
2840: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
2850: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
2860: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 tant. The sqlit
2870: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a e3_libversion().
2880: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 ** function is p
2890: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 rovided for use
28a0: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c in DLLs since DL
28b0: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 L users usually
28c0: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 do not have.** d
28d0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 irect access to
28e0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 string constants
28f0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e within the DLL.
2900: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
2910: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
2920: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ber() function r
2930: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
2940: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 r equal to.** [S
2950: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
2960: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c MBER]. ^The sql
2970: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
2980: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
2990: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
29a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
29b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
29c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
29d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
29e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
29f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a rocessor macro..
2a00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2a10: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
2a20: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
2a30: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
2a40: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2a50: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 char sqlite3_ve
2a60: 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 rsion[] = SQLITE
2a70: 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 _VERSION;.SQLITE
2a80: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2a90: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 *sqlite3_libvers
2aa0: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ion(void);.SQLIT
2ab0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2ac0: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 *sqlite3_source
2ad0: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 id(void);.SQLITE
2ae0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2af0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
2b00: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a er(void);../*.**
2b10: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
2b20: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 ime Library Comp
2b30: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 ilation Options
2b40: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a Diagnostics.**.*
2b50: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2b60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
2b70: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 d() function ret
2b80: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 urns 0 or 1 .**
2b90: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 indicating wheth
2ba0: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 er the specified
2bb0: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 option was defi
2bc0: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 ned at .** compi
2bd0: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 le time. ^The S
2be0: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 QLITE_ prefix ma
2bf0: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f y be omitted fro
2c00: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e m the .** option
2c10: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 name passed to
2c20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
2c30: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a ption_used(). .
2c40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2c50: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
2c60: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 _get() function
2c70: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 allows iterating
2c80: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 .** over the lis
2c90: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 t of options tha
2ca0: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 t were defined a
2cb0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 t compile time b
2cc0: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 y.** returning t
2cd0: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 he N-th compile
2ce0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 time option stri
2cf0: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 ng. ^If N is ou
2d00: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 t of range,.** s
2d10: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
2d20: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 tion_get() retur
2d30: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
2d40: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f r. ^The SQLITE_
2d50: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f .** prefix is o
2d60: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 mitted from any
2d70: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
2d80: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
2d90: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
2da0: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 t()..**.** ^Supp
2db0: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 ort for the diag
2dc0: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 nostic functions
2dd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
2de0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a option_used().**
2df0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d and sqlite3_com
2e00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
2e10: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 may be omitted
2e20: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 by specifying th
2e30: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d e .** [SQLITE_OM
2e40: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
2e50: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 _DIAGS] option a
2e60: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a t compile time..
2e70: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2e80: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 SQL functions [s
2e90: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 qlite_compileopt
2ea0: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ion_used()] and.
2eb0: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 ** [sqlite_compi
2ec0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 leoption_get()]
2ed0: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 and the [compile
2ee0: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d _options pragma]
2ef0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
2f00: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
2f10: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c OPTION_DIAGS.SQL
2f20: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2f30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
2f40: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 n_used(const cha
2f50: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 r *zOptName);.SQ
2f60: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2f70: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
2f80: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
2f90: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
2fa0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
2fb0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
2fc0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
2fd0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
2fe0: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
2ff0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
3000: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
3010: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
3020: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
3030: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e led with mutexin
3040: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 g code omitted d
3050: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 ue to the.** [SQ
3060: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
3070: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
3080: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 tion being set t
3090: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 o 0..**.** SQLit
30a0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 e can be compile
30b0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 d with or withou
30c0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e t mutexes. When
30d0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
30e0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 THREADSAFE] C pr
30f0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
3100: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 is 1 or 2, mute
3110: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
3120: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
3130: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
3140: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
3150: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
3160: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
3170: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
3180: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
3190: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
31a0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
31b0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
31c0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
31d0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
31e0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
31f0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
3200: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
3210: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
3220: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
3230: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
3240: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
3250: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
3260: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
3270: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
3280: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
3290: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
32a0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 e enabled..** ^T
32b0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 he default behav
32c0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 ior is for mutex
32d0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 es to be enabled
32e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
32f0: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
3300: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 ed by an applica
3310: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 tion to make sur
3320: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 e that the.** ve
3330: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 rsion of SQLite
3340: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 that it is linki
3350: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 ng against was c
3360: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
3370: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 the desired sett
3380: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ing of the [SQLI
3390: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
33a0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 acro..**.** This
33b0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 interface only
33c0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 reports on the c
33d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 ompile-time mute
33e0: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 x setting.** of
33f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
3400: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 ADSAFE] flag. I
3410: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
3420: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c iled with.** SQL
3430: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
3440: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 or =2 then mute
3450: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 xes are enabled
3460: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a by default but.*
3470: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f * can be fully o
3480: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 r partially disa
3490: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c bled using a cal
34a0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
34b0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 nfig()].** with
34c0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 the verbs [SQLIT
34d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
34e0: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f HREAD], [SQLITE_
34f0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
3500: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 AD],.** or [SQLI
3510: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
3520: 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 . ^(The return
3530: 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 value of the.**
3540: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
3550: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 fe() function sh
3560: 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d ows only the com
3570: 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e pile-time settin
3580: 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 g of.** thread s
3590: 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 afety, not any r
35a0: 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 un-time changes
35b0: 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 to that setting
35c0: 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 made by.** sqlit
35d0: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 e3_config(). In
35e0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
35f0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
3600: 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 om sqlite3_threa
3610: 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e dsafe().** is un
3620: 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 changed by calls
3630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
3640: 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 ig().)^.**.** Se
3650: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
3660: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 mode] documenta
3670: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
3680: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
3690: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
36a0: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 nt sqlite3_threa
36b0: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a dsafe(void);../*
36c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
36d0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
36e0: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 n Handle.** KEYW
36f0: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 ORDS: {database
3700: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 connection} {dat
3710: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3720: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 s}.**.** Each op
3730: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 en SQLite databa
3740: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 se is represente
3750: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 d by a pointer t
3760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
3770: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 .** the opaque s
3780: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 tructure named "
3790: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 sqlite3". It is
37a0: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b useful to think
37b0: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a of an sqlite3.*
37c0: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 * pointer as an
37d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 object. The [sq
37e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
37f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
3800: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
3810: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
3820: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 terfaces are its
3830: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 constructors, a
3840: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
3850: 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c e()].** and [sql
3860: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d ite3_close_v2()]
3870: 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 are its destruc
3880: 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 tors. There are
3890: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 many other.** i
38a0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 nterfaces (such
38b0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 as.** [sqlite3_p
38c0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
38d0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
38e0: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a nction()], and.*
38f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f * [sqlite3_busy_
3900: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 timeout()] to na
3910: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 me but three) th
3920: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f at are methods o
3930: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 n an.** sqlite3
3940: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 object..*/.typed
3950: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
3960: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 3 sqlite3;../*.*
3970: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 * CAPI3REF: 64-B
3980: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 it Integer Types
3990: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
39a0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
39b0: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 e_uint64.**.** B
39c0: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 ecause there is
39d0: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 no cross-platfor
39e0: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 m way to specify
39f0: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
3a00: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 types.** SQLite
3a10: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 includes typedef
3a20: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 s for 64-bit sig
3a30: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 ned and unsigned
3a40: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a integers..**.**
3a50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 The sqlite3_int
3a60: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 64 and sqlite3_u
3a70: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 int64 are the pr
3a80: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 eferred type def
3a90: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 initions..** The
3aa0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e sqlite_int64 an
3ab0: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 d sqlite_uint64
3ac0: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 types are suppor
3ad0: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ted for backward
3ae0: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 s.** compatibili
3af0: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e ty only..**.** ^
3b00: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
3b10: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 4 and sqlite_int
3b20: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 64 types can sto
3b30: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 re integer value
3b40: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 s.** between -92
3b50: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 2337203685477580
3b60: 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 8 and +922337203
3b70: 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 6854775807 inclu
3b80: 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 sive. ^The.** s
3b90: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e qlite3_uint64 an
3ba0: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 d sqlite_uint64
3bb0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 types can store
3bc0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a integer values .
3bd0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ** between 0 and
3be0: 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 +18446744073709
3bf0: 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 551615 inclusive
3c00: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
3c10: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 TE_INT64_TYPE.
3c20: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 typedef SQLITE_I
3c30: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 NT64_TYPE sqlite
3c40: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
3c50: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 f unsigned SQLIT
3c60: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
3c70: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 ite_uint64;.#eli
3c80: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 f defined(_MSC_V
3c90: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f ER) || defined(_
3ca0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 _BORLANDC__). t
3cb0: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 ypedef __int64 s
3cc0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
3cd0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
3ce0: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 __int64 sqlite_u
3cf0: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 int64;.#else. t
3d00: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 ypedef long long
3d10: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 int sqlite_int6
3d20: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
3d30: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 igned long long
3d40: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 int sqlite_uint6
3d50: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 4;.#endif.typede
3d60: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 f sqlite_int64 s
3d70: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 qlite3_int64;.ty
3d80: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e pedef sqlite_uin
3d90: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 t64 sqlite3_uint
3da0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 64;../*.** If co
3db0: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 mpiling for a pr
3dc0: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 ocessor that lac
3dd0: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ks floating poin
3de0: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 t support,.** su
3df0: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 bstitute integer
3e00: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f for floating-po
3e10: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 int..*/.#ifdef S
3e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 QLITE_OMIT_FLOAT
3e30: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 ING_POINT.# defi
3e40: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 ne double sqlite
3e50: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 3_int64.#endif..
3e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3e70: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 Closing A Databa
3e80: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se Connection.**
3e90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
3ea0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c _close() and sql
3eb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
3ec0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
3ed0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 tructors.** for
3ee0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
3ef0: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 ject..** ^Calls
3f00: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 to sqlite3_close
3f10: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
3f20: 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e lose_v2() return
3f30: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a 2a SQLITE_OK if.**
3f40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
3f50: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 bject is success
3f60: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 fully destroyed
3f70: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 and all associat
3f80: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 ed.** resources
3f90: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
3fa0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 .**.** ^If the d
3fb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3fc0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 on is associated
3fd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
3fe0: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 d prepared.** st
3ff0: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 atements or unfi
4000: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
4010: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 ackup objects th
4020: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 en sqlite3_close
4030: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 ().** will leave
4040: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
4050: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e nnection open an
4060: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
4070: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 _BUSY]..** ^If s
4080: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
4090: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 ) is called with
40a0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
40b0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
40c0: 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73 68 .** and unfinish
40d0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ed sqlite3_backu
40e0: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 ps, then the dat
40f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4100: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 becomes.** an u
4110: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 nusable "zombie"
4120: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f which will auto
4130: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 matically be dea
4140: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 llocated when th
4150: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 e.** last prepar
4160: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
4170: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 finalized or the
4180: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 last sqlite3_ba
4190: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 ckup is.** finis
41a0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 hed. The sqlite
41b0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 3_close_v2() int
41c0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 erface is intend
41d0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a ed for use with.
41e0: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 ** host language
41f0: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61 s that are garba
4200: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e ge collected, an
4210: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 d where the orde
4220: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 r in which.** de
4230: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 structors are ca
4240: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72 lled is arbitrar
4250: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 y..**.** Applica
4260: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
4270: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
4280: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
4290: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
42a0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 nts],.** [sqlite
42b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 3_blob_close | c
42c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 lose] all [BLOB
42d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a handles], and .*
42e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
42f0: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 p_finish | finis
4300: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f h] all [sqlite3_
4310: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 backup] objects
4320: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 associated.** wi
4330: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d th the [sqlite3]
4340: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f object prior to
4350: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 attempting to c
4360: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e lose the object.
4370: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 ^If.** sqlite3
4380: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 _close_v2() is c
4390: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 alled on a [data
43a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
43b0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a that still has.
43c0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b ** outstanding [
43d0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
43e0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 nts], [BLOB hand
43f0: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 les], and/or.**
4400: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
4410: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 objects then it
4420: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
4430: 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c OK but the deall
4440: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 ocation.** of re
4450: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 sources is defer
4460: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 red until all [p
4470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
4480: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
4490: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c es],.** and [sql
44a0: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
44b0: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 ects are also de
44c0: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e stroyed..**.** ^
44d0: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 If an [sqlite3]
44e0: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f object is destro
44f0: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e yed while a tran
4500: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
4510: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
4520: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
4530: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
4540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
4550: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
4560: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e te3_close(C)] an
4570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
4580: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 _v2(C)].** must
4590: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
45a0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 .** pointer or a
45b0: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
45c0: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 ct pointer obtai
45d0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
45e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
45f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
4600: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
4610: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
4620: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
4630: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c closed..** ^Call
4640: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ing sqlite3_clos
4650: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
4660: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 lose_v2() with a
4670: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
4680: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 argument is a h
4690: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
46a0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
46b0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 sqlite3_close(s
46c0: 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
46d0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
46e0: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 _close_v2(sqlite
46f0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 3*);../*.** The
4700: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 type for a callb
4710: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ack function..**
4720: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 This is legacy
4730: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 and deprecated.
4740: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 It is included
4750: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a for historical.*
4760: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 * compatibility
4770: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d and is not docum
4780: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 ented..*/.typede
4790: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f f int (*sqlite3_
47a0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
47b0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 int,char**, char
47c0: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 **);../*.** CAPI
47d0: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 3REF: One-Step Q
47e0: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 uery Execution I
47f0: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 nterface.**.** T
4800: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
4810: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 ) interface is a
4820: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 convenience wra
4830: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
4840: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
4850: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
4860: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
4870: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
4880: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 ],.** that allow
4890: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
48a0: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 to run multiple
48b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 statements of S
48c0: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 QL.** without ha
48d0: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f ving to use a lo
48e0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a t of C code. .**
48f0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
4900: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 _exec() interfac
4910: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d e runs zero or m
4920: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ore UTF-8 encode
4930: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d d,.** semicolon-
4940: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 separate SQL sta
4950: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
4960: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 nto its 2nd argu
4970: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 ment,.** in the
4980: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b context of the [
4990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
49a0: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 ion] passed in a
49b0: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 s its 1st.** arg
49c0: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 ument. ^If the
49d0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
49e0: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 n of the 3rd arg
49f0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 ument to.** sqli
4a00: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
4a10: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 t NULL, then it
4a20: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 is invoked for e
4a30: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a ach result row.*
4a40: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 * coming out of
4a50: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 the evaluated SQ
4a60: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e L statements. ^
4a70: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
4a80: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 to.** sqlite3_e
4a90: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 xec() is relayed
4aa0: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
4ab0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 1st argument of
4ac0: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b each.** callback
4ad0: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 invocation. ^I
4ae0: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 f the callback p
4af0: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
4b00: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 3_exec().** is N
4b10: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c ULL, then no cal
4b20: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e lback is ever in
4b30: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 voked and result
4b40: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e rows are.** ign
4b50: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ored..**.** ^If
4b60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
4b70: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 while evaluating
4b80: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
4b90: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a nts passed into.
4ba0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
4bb0: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f ), then executio
4bc0: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
4bd0: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 statement stops
4be0: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 and.** subseque
4bf0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 nt statements ar
4c00: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 e skipped. ^If
4c10: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
4c20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
4c30: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 c().** is not NU
4c40: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f LL then any erro
4c50: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 r message is wri
4c60: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
4c70: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
4c80: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
4c90: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 c()] and passed
4ca0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 back through the
4cb0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 5th parameter..
4cc0: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f ** To avoid memo
4cd0: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 ry leaks, the ap
4ce0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
4cf0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
4d00: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 _free()].** on e
4d10: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
4d20: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 ings returned th
4d30: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
4d40: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 rameter of.** of
4d50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4d60: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 after the error
4d70: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
4d80: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
4d90: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 ed..** ^If the 5
4da0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
4db0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
4dc0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e s not NULL and n
4dd0: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 o errors.** occu
4de0: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
4df0: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 exec() sets the
4e00: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 pointer in its 5
4e10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a th parameter to.
4e20: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 ** NULL before r
4e30: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
4e40: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 ^If an sqlite3_e
4e50: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 xec() callback r
4e60: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
4e70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
4e80: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 c().** routine r
4e90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 eturns SQLITE_AB
4ea0: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f ORT without invo
4eb0: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 king the callbac
4ec0: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 k again and.** w
4ed0: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 ithout running a
4ee0: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 ny subsequent SQ
4ef0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
4f00: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 .** ^The 2nd arg
4f10: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
4f20: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c ite3_exec() call
4f30: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 back function is
4f40: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
4f50: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
4f60: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 result. ^The 3
4f70: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rd argument to t
4f80: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
4f90: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 ).** callback is
4fa0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
4fb0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
4fc0: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 obtained as if
4fd0: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
4fe0: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
4ff0: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f one for each co
5000: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c lumn. ^If an el
5010: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 ement of a.** re
5020: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c sult row is NULL
5030: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 then the corres
5040: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 ponding string p
5050: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a ointer for the.*
5060: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
5070: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e callback is a N
5080: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 ULL pointer. ^T
5090: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 he 4th argument
50a0: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 to the.** sqlite
50b0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
50c0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
50d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
50e0: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a ings where each.
50f0: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 ** entry represe
5100: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 nts the name of
5110: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 corresponding re
5120: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f sult column as o
5130: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
5140: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
5150: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e name()]..**.** ^
5160: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d If the 2nd param
5170: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
5180: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c exec() is a NULL
5190: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e pointer, a poin
51a0: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 ter.** to an emp
51b0: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 ty string, or a
51c0: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e pointer that con
51d0: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 tains only white
51e0: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a space and/or .**
51f0: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 SQL comments, t
5200: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 hen no SQL state
5210: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 ments are evalua
5220: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 ted and the data
5230: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 base.** is not c
5240: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 hanged..**.** Re
5250: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a strictions:.**.*
5260: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
5270: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
5280: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
5290: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
52a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
52b0: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 c().** is a
52c0: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 valid and open
52d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
52e0: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 tion]..** <li> T
52f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
5300: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 ust not close th
5310: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
5320: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
5330: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 d by.** the
5340: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
5350: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
5360: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
5370: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
5380: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
5390: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
53a0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 ot modify the SQ
53b0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
53c0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
53d0: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 the 2nd par
53e0: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
53f0: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
5400: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
5410: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 running..** </u
5420: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l>.*/.SQLITE_API
5430: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 int sqlite3_exe
5440: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
5450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5470: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
5480: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
5490: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
54b0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
54c0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
54d0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 int (*callback)(
54e0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
54f0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 ,char**), /* Ca
5500: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
5510: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
5520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5530: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5540: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 /* 1st argument
5550: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 to callback */.
5560: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
5570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5580: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
5590: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
55a0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a here */.);../*.
55b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
55c0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
55d0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
55e0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
55f0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
5600: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
5610: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
5620: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
5630: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
5640: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
5650: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
5660: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
5670: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
5680: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 der to indicate
5690: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 success or failu
56a0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 re..**.** New er
56b0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 ror codes may be
56c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
56d0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
56e0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ite..**.** See a
56f0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 lso: [SQLITE_IOE
5700: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 RR_READ | extend
5710: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
5720: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 ,.** [sqlite3_vt
5730: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 ab_on_conflict()
5740: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 ] [SQLITE_ROLLBA
5750: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 CK | result code
5760: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s]..*/.#define S
5770: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 QLITE_OK
5780: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 0 /* Succes
5790: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f sful result */./
57a0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 * beginning-of-e
57b0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 rror-codes */.#d
57c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 efine SQLITE_ERR
57d0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a OR 1 /*
57e0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 SQL error or mi
57f0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a ssing database *
5800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5810: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 _INTERNAL 2
5820: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f /* Internal lo
5830: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c gic error in SQL
5840: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ite */.#define S
5850: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 QLITE_PERM
5860: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 3 /* Access
5870: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 permission deni
5880: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
5890: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 LITE_ABORT
58a0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 4 /* Callbac
58b0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 k routine reques
58c0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a ted an abort */.
58d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
58e0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 USY 5
58f0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
5900: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a file is locked *
5910: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5920: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 _LOCKED 6
5930: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 /* A table in
5940: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
5950: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
5960: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 e SQLITE_NOMEM
5970: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 7 /* A m
5980: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a alloc() failed *
5990: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
59a0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 _READONLY 8
59b0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 /* Attempt to
59c0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 write a readonly
59d0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
59f0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 RRUPT 9 /*
5a00: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e Operation termin
5a10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
5a20: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 interrupt()*/.#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5a40: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a RR 10 /*
5a50: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 Some kind of di
5a60: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 sk I/O error occ
5a70: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 urred */.#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 SQLITE_CORRUPT
5a90: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 11 /* The
5aa0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d database disk im
5ab0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 age is malformed
5ac0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5ad0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 TE_NOTFOUND 1
5ae0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 2 /* Unknown o
5af0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 pcode in sqlite3
5b00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 _file_control()
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5b20: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
5b30: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
5b40: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
5b50: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
5b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
5b80: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
5b90: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
5ba0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
5bb0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
5bc0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 L 15 /* Dat
5bd0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
5be0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
5bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
5c00: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
5c10: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
5c20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5c30: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
5c40: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
5c50: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
5c60: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
5c70: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
5c80: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
5c90: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
5ca0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
5cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5cc0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
5cd0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
5ce0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
5cf0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
5d00: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
5d10: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
5d20: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
5d40: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
5d50: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
5d60: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
5d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
5d80: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
5d90: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
5da0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
5db0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
5dd0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
5de0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
5df0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
5e00: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
5e10: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
5e20: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
5e30: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
5e50: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
5e60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
5e70: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
5e80: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
5e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
5ea0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
5eb0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
5ec0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
5ed0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
5ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 ine SQLITE_NOTIC
5ef0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e E 27 /* N
5f00: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f otifications fro
5f10: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 m sqlite3_log()
5f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5f30: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 E_WARNING 28
5f40: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 /* Warnings f
5f50: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 rom sqlite3_log(
5f60: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5f70: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
5f80: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
5f90: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
5fa0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
5fb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
5fc0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
5fd0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
5fe0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
5ff0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
6000: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
6010: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
6020: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
6030: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b esult Codes.** K
6040: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 EYWORDS: {extend
6050: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b ed error code} {
6060: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
6070: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 odes}.** KEYWORD
6080: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 S: {extended res
6090: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e ult code} {exten
60a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
60b0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 }.**.** In its d
60c0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
60d0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 tion, SQLite API
60e0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
60f0: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 one of 26 integ
6100: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b er.** [SQLITE_OK
6110: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d | result codes]
6120: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 . However, expe
6130: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e rience has shown
6140: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a that many of.**
6150: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f these result co
6160: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 des are too coar
6170: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 se-grained. The
6180: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 y do not provide
6190: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f as.** much info
61a0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 rmation about pr
61b0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 oblems as progra
61c0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 mmers might like
61d0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 . In an effort
61e0: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 to.** address th
61f0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f is, newer versio
6200: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 ns of SQLite (ve
6210: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 rsion 3.3.8 and
6220: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a later) include.*
6230: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 * support for ad
6240: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 ditional result
6250: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 codes that provi
6260: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 de more detailed
6270: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
6280: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 about errors. Th
6290: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
62a0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 t codes are enab
62b0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
62c0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 ** on a per data
62d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
62e0: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a basis using the.
62f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 ** [sqlite3_exte
6300: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
6310: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 s()] API..**.**
6320: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 Some of the avai
6330: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 lable extended r
6340: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 esult codes are
6350: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 listed here..**
6360: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 One may expect t
6370: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 he number of ext
6380: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
6390: 65 73 20 77 69 6c 6c 20 69 6e 63 72 65 61 73 65 es will increase
63a0: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 .** over time.
63b0: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 Software that us
63c0: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 es extended resu
63d0: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 lt codes should
63e0: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 expect.** to see
63f0: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 new result code
6400: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 s in future rele
6410: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
6420: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
6430: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 _OK result code
6440: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 will never be ex
6450: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c tended. It will
6460: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 always.** be ex
6470: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 actly zero..*/.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6490: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 ERR_READ
64a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
64b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<8)).#d
64c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
64d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
64e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
64f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RR | (2<<8)).#de
6500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
6510: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 R_WRITE
6520: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
6530: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 R | (3<<8)).#def
6540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
6550: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 _FSYNC
6560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
6570: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
6580: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
6590: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 DIR_FSYNC
65a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
65b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
65c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
65d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 RUNCATE
65e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
65f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (6<<8)).#define
6600: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
6610: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 TAT
6620: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
6630: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
6640: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c SQLITE_IOERR_UNL
6650: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
6660: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
6670: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
6680: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f QLITE_IOERR_RDLO
6690: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 CK (S
66a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
66b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
66c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
66d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 E (SQ
66e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 LITE_IOERR | (10
66f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6700: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
6710: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ED (SQ
6720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 LITE_IOERR | (11
6730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6740: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d LITE_IOERR_NOMEM
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 LITE_IOERR | (12
6770: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6780: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
6790: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 S (SQ
67a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 LITE_IOERR | (13
67b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
67c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b LITE_IOERR_CHECK
67d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 RESERVEDLOCK (SQ
67e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 LITE_IOERR | (14
67f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6800: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 LITE_IOERR_LOCK
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 LITE_IOERR | (15
6830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6840: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 LITE_IOERR_CLOSE
6850: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6860: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 LITE_IOERR | (16
6870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6880: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 LITE_IOERR_DIR_C
6890: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 LOSE (SQ
68a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 LITE_IOERR | (17
68b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
68c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 LITE_IOERR_SHMOP
68d0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 EN (SQ
68e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 LITE_IOERR | (18
68f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6900: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 LITE_IOERR_SHMSI
6910: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ZE (SQ
6920: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 LITE_IOERR | (19
6930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6940: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f LITE_IOERR_SHMLO
6950: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 CK (SQ
6960: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 LITE_IOERR | (20
6970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6980: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 LITE_IOERR_SHMMA
6990: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 P (SQ
69a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 LITE_IOERR | (21
69b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
69c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 LITE_IOERR_SEEK
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
69e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 LITE_IOERR | (22
69f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6a00: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
6a10: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 E_NOENT (SQ
6a20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 LITE_IOERR | (23
6a30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6a40: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 LITE_IOERR_MMAP
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6a60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 LITE_IOERR | (24
6a70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6a80: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 LITE_IOERR_GETTE
6a90: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 MPPATH (SQ
6aa0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 LITE_IOERR | (25
6ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6ac0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 LITE_IOERR_CONVP
6ad0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 ATH (SQ
6ae0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 LITE_IOERR | (26
6af0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6b00: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 LITE_LOCKED_SHAR
6b10: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 EDCACHE (SQ
6b20: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 LITE_LOCKED | (
6b30: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
6b40: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 QLITE_BUSY_RECOV
6b50: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 ERY (S
6b60: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 QLITE_BUSY |
6b70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
6b80: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 SQLITE_BUSY_SNAP
6b90: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 SHOT (
6ba0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 SQLITE_BUSY |
6bb0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
6bc0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
6bd0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 _NOTEMPDIR
6be0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
6bf0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
6c00: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
6c10: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 EN_ISDIR
6c20: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
6c30: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 EN | (2<<8)).#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
6c50: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 OPEN_FULLPATH
6c60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
6c70: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OPEN | (3<<8)).#
6c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
6c90: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 NTOPEN_CONVPATH
6ca0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
6cb0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 NTOPEN | (4<<8))
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6cd0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
6ce0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
6cf0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
6d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
6d10: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
6d20: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
6d30: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
6d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
6d50: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
6d60: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
6d70: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
6d80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6d90: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f LITE_READONLY_RO
6da0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 LLBACK (SQ
6db0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
6dc0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
6dd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
6de0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 DBMOVED (
6df0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
6e00: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
6e10: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 e SQLITE_ABORT_R
6e20: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 OLLBACK
6e30: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c (SQLITE_ABORT |
6e40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
6e50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6e60: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 NT_CHECK
6e70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6e80: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NT | (1<<8)).#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
6ea0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f TRAINT_COMMITHOO
6eb0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 K (SQLITE_CONS
6ec0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 TRAINT | (2<<8))
6ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6ee0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 CONSTRAINT_FOREI
6ef0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f GNKEY (SQLITE_
6f00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c CONSTRAINT | (3<
6f10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
6f20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
6f30: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c UNCTION (SQL
6f40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
6f50: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
6f60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6f70: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 NT_NOTNULL
6f80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6f90: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 NT | (5<<8)).#de
6fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
6fb0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 TRAINT_PRIMARYKE
6fc0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
6fd0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 TRAINT | (6<<8))
6fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6ff0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 CONSTRAINT_TRIGG
7000: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f ER (SQLITE_
7010: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c CONSTRAINT | (7<
7020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7030: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 ITE_CONSTRAINT_U
7040: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c NIQUE (SQL
7050: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
7060: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
7070: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
7080: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 NT_VTAB
7090: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
70a0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 NT | (9<<8)).#de
70b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
70c0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 TRAINT_ROWID
70d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
70e0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 TRAINT |(10<<8))
70f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7100: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 NOTICE_RECOVER_W
7110: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f AL (SQLITE_
7120: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 NOTICE | (1<<8))
7130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7140: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 NOTICE_RECOVER_R
7150: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f OLLBACK (SQLITE_
7160: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 NOTICE | (2<<8))
7170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7180: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 WARNING_AUTOINDE
7190: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f X (SQLITE_
71a0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 WARNING | (1<<8)
71b0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
71c0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
71d0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
71e0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 s.**.** These bi
71f0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 t values are int
7200: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
7210: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 the.** 3rd para
7220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
7230: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
7240: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a interface and.*
7250: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 * in the 4th par
7260: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
7270: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7280: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 ] method..*/.#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
72a0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 _READONLY
72b0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 0x00000001 /*
72c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
72d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
72e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
72f0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 _READWRITE
7300: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 0x00000002 /*
7310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
7320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
7330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7340: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 _CREATE
7350: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 0x00000004 /*
7360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
7370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
7380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7390: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 _DELETEONCLOSE
73a0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 0x00000008 /*
73b0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
73c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
73d0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 _EXCLUSIVE
73e0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 0x00000010 /*
73f0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7410: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 _AUTOPROXY
7420: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 0x00000020 /*
7430: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7450: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 _URI
7460: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 0x00000040 /*
7470: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
7480: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
7490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
74a0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 _MEMORY
74b0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 0x00000080 /*
74c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
74d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
74e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
74f0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 _MAIN_DB
7500: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 0x00000100 /*
7510: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7530: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 _TEMP_DB
7540: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 0x00000200 /*
7550: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7570: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 _TRANSIENT_DB
7580: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 0x00000400 /*
7590: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
75a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
75b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 _MAIN_JOURNAL
75c0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 0x00000800 /*
75d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
75e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
75f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 _TEMP_JOURNAL
7600: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 0x00001000 /*
7610: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7630: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 _SUBJOURNAL
7640: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 0x00002000 /*
7650: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
7660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7670: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 _MASTER_JOURNAL
7680: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 0x00004000 /*
7690: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
76a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
76b0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 _NOMUTEX
76c0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 0x00008000 /*
76d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
76e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
76f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7700: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 _FULLMUTEX
7710: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 0x00010000 /*
7720: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
7730: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
7740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
7750: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 _SHAREDCACHE
7760: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 0x00020000 /*
7770: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
7780: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
7790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
77a0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 _PRIVATECACHE
77b0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 0x00040000 /*
77c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
77d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
77e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
77f0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
7800: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 0x00080000 /*
7810: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a VFS only */../*
7820: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 Reserved:
7830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
7840: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0x00F00000 */
7850: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7860: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
7870: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
7880: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
7890: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
78a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
78b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
78c0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 object returns a
78d0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
78e0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 is a vector of t
78f0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 hese.** bit valu
7900: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f es expressing I/
7910: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 O characteristic
7920: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 s of the mass st
7930: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 orage.** device
7940: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 that holds the f
7950: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 ile that the [sq
7960: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
7970: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a ].** refers to..
7980: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
7990: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
79a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
79b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
79c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
79d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
79e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
79f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
7a00: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
7a10: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
7a20: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
7a30: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
7a40: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
7a50: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
7a60: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
7a70: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
7a80: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
7a90: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
7aa0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
7ab0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
7ac0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
7ad0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
7ae0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
7af0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
7b00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
7b10: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
7b20: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
7b30: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
7b40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
7b50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
7b60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
7b70: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
7b80: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
7b90: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
7ba0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
7bb0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 to xWrite(). Th
7bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
7bd0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
7be0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e TE property mean
7bf0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 s that.** after
7c00: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 reboot following
7c10: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 a crash or powe
7c20: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 r loss, the only
7c30: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 bytes in a.** f
7c40: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 ile that were wr
7c50: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 itten at the app
7c60: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d lication level m
7c70: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 ight have change
7c80: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 d.** and that ad
7c90: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 jacent bytes, ev
7ca0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 en bytes within
7cb0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 the same sector
7cc0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 are.** guarantee
7cd0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 d to be unchange
7ce0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
7cf0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
7d00: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c _WHEN_OPEN.** fl
7d10: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 ag indicate that
7d20: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 a file cannot b
7d30: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f e deleted when o
7d40: 70 65 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 pen..*/.#define
7d50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7d60: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
7d70: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
7d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7d90: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
7da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
7db0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
7dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7dd0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
7de0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
7df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
7e00: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
7e10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
7e20: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
7e30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
7e40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
7e50: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
7e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
7e70: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
7e80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
7e90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
7ea0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
7eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
7ec0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
7ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7ee0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
7ef0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
7f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7f10: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
7f20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
7f30: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
7f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
7f50: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
7f60: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
7f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7f80: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
7f90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7fa0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
7fb0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
7fc0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
7fd0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
7fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
7ff0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
8000: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
8010: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
8020: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
8030: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 Levels.**.** SQ
8040: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 Lite uses one of
8050: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
8060: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
8070: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
8080: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
8090: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
80a0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
80b0: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
80c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
80d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
80e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
80f0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
8100: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
8110: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
8120: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
8130: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
8140: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
8150: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
8160: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
8170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
8180: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
8190: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
81a0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
81b0: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a tion Type Flags.
81c0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
81d0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
81e0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
81f0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
8200: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
8210: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
8220: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 ination of.** th
8230: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ese integer valu
8240: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 es as the second
8250: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
8260: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 When the SQLITE
8270: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 _SYNC_DATAONLY f
8280: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 lag is used, it
8290: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a means that the.*
82a0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e * sync operation
82b0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 only needs to f
82c0: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 lush data to mas
82d0: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 s storage. Inod
82e0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
82f0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 need not be flu
8300: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 shed. If the low
8310: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 er four bits of
8320: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 the flag.** equa
8330: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f l SQLITE_SYNC_NO
8340: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 RMAL, that means
8350: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 to use normal f
8360: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 sync() semantics
8370: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 ..** If the lowe
8380: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 r four bits equa
8390: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 l SQLITE_SYNC_FU
83a0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a LL, that means.*
83b0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 * to use Mac OS
83c0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
83d0: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
83e0: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f c()..**.** Do no
83f0: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 t confuse the SQ
8400: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
8410: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
8420: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 _FULL flags.** w
8430: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 ith the [PRAGMA
8440: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 synchronous]=NOR
8450: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 MAL and [PRAGMA
8460: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c synchronous]=FUL
8470: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 L.** settings.
8480: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 The [synchronous
8490: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 pragma] determi
84a0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 nes when calls t
84b0: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 o the.** xSync V
84c0: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 FS method occur
84d0: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 and applies unif
84e0: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c ormly across all
84f0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 platforms..** T
8500: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
8510: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
8520: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
8530: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a determine how.*
8540: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 * energetic or r
8550: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 igorous or force
8560: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 ful the sync ope
8570: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a rations are and.
8580: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 ** only make a d
8590: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 ifference on Mac
85a0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 OSX for the def
85b0: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 ault SQLite code
85c0: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 ..** (Third-part
85d0: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 y VFS implementa
85e0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f tions might also
85f0: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
8600: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e ction.** between
8610: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
8620: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
8630: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d YNC_FULL, but am
8640: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 ong the.** opera
8650: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 ting systems nat
8660: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 ively supported
8670: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 by SQLite, only
8680: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 Mac OSX.** cares
8690: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 about the diffe
86a0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 rence.).*/.#defi
86b0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e ne SQLITE_SYNC_N
86c0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 ORMAL 0x0
86d0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
86e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 ITE_SYNC_FULL
86f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 0x00003.#
8700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
8710: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 NC_DATAONLY
8720: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 0x00010../*.**
8730: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
8740: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 erface Open File
8750: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e Handle.**.** An
8760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
8770: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
8780: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 s an open file i
8790: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 n the .** [sqlit
87a0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 e3_vfs | OS inte
87b0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 rface layer]. I
87c0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
87d0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d erface.** implem
87e0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a entations will.*
87f0: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 * want to subcla
8800: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 ss this object b
8810: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 y appending addi
8820: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a tional fields.**
8830: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 for their own u
8840: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 se. The pMethod
8850: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 s entry is a poi
8860: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
8870: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
8880: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
8890: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 efines methods f
88a0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a or performing.**
88b0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
88c0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 on the open file
88d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
88e0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
88f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 sqlite3_file;.s
8900: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
8910: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 le {. const str
8920: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
8930: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 ethods *pMethods
8940: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f ; /* Methods fo
8950: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a r an open file *
8960: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
8970: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
8980: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 ce File Virtual
8990: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a Methods Object.*
89a0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 *.** Every file
89b0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 opened by the [s
89c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
89d0: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 ] method populat
89e0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 es an.** [sqlite
89f0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 3_file] object (
8a00: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c or, more commonl
8a10: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 y, a subclass of
8a20: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
8a30: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 _file] object) w
8a40: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
8a50: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
8a60: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 this object..**
8a70: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 This object defi
8a80: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 nes the methods
8a90: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
8aa0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
8ab0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 ns.** against th
8ac0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 e open file repr
8ad0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b esented by the [
8ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
8af0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ject..**.** If t
8b00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
8b10: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 xOpen] method se
8b20: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
8b30: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
8b40: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
8b50: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
8b60: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
8b70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
8b80: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
8b90: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
8ba0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 if the [sqlite3
8bb0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f _vfs.xOpen] repo
8bc0: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 rted that it fai
8bd0: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c led. The.** onl
8be0: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 y way to prevent
8bf0: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 a call to xClos
8c00: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 e following a fa
8c10: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 iled [sqlite3_vf
8c20: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 s.xOpen].** is f
8c30: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
8c40: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 vfs.xOpen] to se
8c50: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
8c60: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
8c70: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a ent.** to NULL..
8c80: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
8c90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
8ca0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
8cb0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
8cc0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
8cd0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
8ce0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
8cf0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
8d00: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
8d10: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
8d20: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
8d30: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
8d40: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
8d50: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
8d60: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
8d70: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
8d80: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
8d90: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
8da0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
8db0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
8dc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
8dd0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
8de0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
8df0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
8e00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
8e10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
8e20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
8e30: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
8e40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8e50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
8e60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8e70: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
8e80: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
8e90: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
8ea0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
8eb0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
8ec0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
8ed0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
8ee0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
8ef0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
8f00: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
8f10: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
8f20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
8f30: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
8f40: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
8f50: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
8f60: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
8f70: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
8f80: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
8f90: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
8fa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
8fb0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
8fc0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
8fd0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
8fe0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
8ff0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
9000: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
9010: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
9020: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
9030: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
9040: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
9050: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
9060: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
9070: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
9080: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9090: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
90a0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
90b0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
90c0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
90d0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
90e0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
90f0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
9100: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
9110: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
9120: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
9130: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
9140: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
9150: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
9160: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
9170: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
9180: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
9190: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
91a0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
91b0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
91c0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
91d0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
91e0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
91f0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
9200: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
9210: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
9220: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
9230: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
9240: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
9250: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
9260: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
9270: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
9280: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
9290: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 wn use..** A [SQ
92a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
92b0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f TATE | list of o
92c0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
92d0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
92e0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
92f0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
9300: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
9310: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
9320: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
9330: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
9340: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
9350: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
9360: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
9370: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
9380: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
9390: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
93a0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
93b0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
93c0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
93d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
93e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
93f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
9400: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
9410: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
9420: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
9430: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
9440: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
9450: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
9460: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
9470: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
9480: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
9490: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
94a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
94b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
94c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
94d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
94e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
94f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
9500: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
9510: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
9520: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
9530: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
9540: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
9550: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9560: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
9570: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
9590: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
95a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
95b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
95c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
95d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
95e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
95f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
9600: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
9610: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
9620: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
9630: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
9640: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
9650: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
9660: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
9670: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
9680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
9690: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
96a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
96b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
96c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
96d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
96e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
96f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
9700: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
9710: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
9720: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
9730: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
9740: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
9750: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
9760: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
9770: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
9780: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
9790: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
97a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
97b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
97c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
97d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
97e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
97f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
9800: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
9810: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
9820: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
9830: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
9840: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
9850: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
9860: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
9870: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
9880: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
9890: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
98a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
98b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
98c0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
98d0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
98e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
98f0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
9900: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
9910: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
9920: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
9930: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
9940: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
9950: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
9960: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
9970: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
9980: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
9990: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
99a0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
99b0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
99c0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
99d0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
99e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
99f0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
9a00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
9a10: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
9a20: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
9a30: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
9a40: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
9a50: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
9a60: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
9a70: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
9a80: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
9a90: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
9aa0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
9ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
9ac0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
9ad0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
9ae0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
9af0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
9b00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
9b10: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
9b20: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
9b30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
9b40: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
9b50: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
9b60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
9b70: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
9b80: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
9b90: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
9ba0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
9bb0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
9bc0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
9bd0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
9be0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
9bf0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
9c00: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
9c10: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
9c20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
9c30: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
9c40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
9c50: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
9c60: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
9c70: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
9c80: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
9c90: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
9ca0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
9cb0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
9cc0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
9cd0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
9ce0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
9cf0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
9d00: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
9d10: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
9d20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
9d30: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
9d40: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
9d50: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
9d60: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
9d70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
9d80: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
9d90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
9da0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
9db0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
9dc0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
9dd0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
9de0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
9df0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
9e00: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
9e10: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
9e20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
9e30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
9e40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
9e50: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
9e60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
9e70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
9e80: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
9e90: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
9ea0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
9eb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
9ec0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
9ed0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
9ee0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
9ef0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a rol Opcodes.**.*
9f00: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
9f10: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 constants are op
9f20: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 codes for the xF
9f30: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
9f40: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c d.** of the [sql
9f50: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
9f60: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 object and for
9f70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
9f80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 e_control()].**
9f90: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
9fa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
9fb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 TL_LOCKSTATE] op
9fc0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
9fd0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
9fe0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
9ff0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
a000: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 rol method to wr
a010: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 ite the current
a020: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 state of.** the
a030: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 lock (one of [SQ
a040: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
a050: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
a060: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ARED],.** [SQLIT
a070: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
a080: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 , [SQLITE_LOCK_P
a090: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c ENDING], or [SQL
a0a0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
a0b0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 VE]).** into an
a0c0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 integer that the
a0d0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 pArg argument p
a0e0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 oints to. This c
a0f0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
a100: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
a110: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 ing and only nee
a120: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ds to be support
a130: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 ed when SQLITE_T
a140: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 EST.** is define
a150: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c d..** <ul>.** <l
a160: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a170: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 _SIZE_HINT]].**
a180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a190: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 L_SIZE_HINT] opc
a1a0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 ode is used by S
a1b0: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 QLite to give th
a1c0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 e VFS.** layer a
a1d0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 hint of how lar
a1e0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
a1f0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 file will grow t
a200: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a o be during the.
a210: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 ** current trans
a220: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 action. This hi
a230: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e nt is not guaran
a240: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 teed to be accur
a250: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 ate but it.** is
a260: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 often close. T
a270: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 he underlying VF
a280: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 S might choose t
a290: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 o preallocate da
a2a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 tabase.** file s
a2b0: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 pace based on th
a2c0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 is hint in order
a2d0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 to help writes
a2e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
a2f0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 ** file run fast
a300: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b er..**.** <li>[[
a310: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
a320: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 NK_SIZE]].** The
a330: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
a340: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 HUNK_SIZE] opcod
a350: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 e is used to req
a360: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 uest that the VF
a370: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 S.** extends and
a380: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 truncates the d
a390: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 atabase file in
a3a0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 chunks of a size
a3b0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
a3c0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 the user. The f
a3d0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
a3e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f o [sqlite3_file_
a3f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c control()] shoul
a400: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 d .** point to a
a410: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 n integer (type
a420: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 int) containing
a430: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 the new chunk-si
a440: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 ze to use.** for
a450: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 the nominated d
a460: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 atabase. Allocat
a470: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c ing database fil
a480: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 e space in large
a490: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 .** chunks (say
a4a0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 1MB at a time),
a4b0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d may reduce file-
a4c0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 system fragmenta
a4d0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 tion and.** impr
a4e0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ove performance
a4f0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e on some systems.
a500: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a510: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
a520: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
a530: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
a540: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f LE_POINTER] opco
a550: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
a560: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
a570: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
a580: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
a590: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
a5a0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
a5b0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
a5c0: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 on. See the [sq
a5d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
a5e0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 ol()] documentat
a5f0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 ion for.** addit
a600: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
a610: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 n..**.** <li>[[S
a620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
a630: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f _OMITTED]].** No
a640: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a longer in use..
a650: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a660: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a TE_FCNTL_SYNC]].
a670: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
a680: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 CNTL_SYNC] opcod
a690: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
a6a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
a6b0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 ite and.** sent
a6c0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 to the VFS immed
a6d0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 iately before th
a6e0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
a6f0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a s invoked on a.*
a700: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 * database file
a710: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 descriptor. Or,
a720: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 if the xSync met
a730: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b hod is not invok
a740: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 ed .** because t
a750: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 he user has conf
a760: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 igured SQLite wi
a770: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 th .** [PRAGMA s
a780: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
a790: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
a7a0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b OFF] it is invok
a7b0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 ed in place .**
a7c0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 of the xSync met
a7d0: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 hod. In most cas
a7e0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 es, the pointer
a7f0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
a800: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c with.** this fil
a810: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c e-control is NUL
a820: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 L. However, if t
a830: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
a840: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 is being synced
a850: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 .** as part of a
a860: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 multi-database
a870: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 commit, the argu
a880: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
a890: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a nul-terminated.
a8a0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
a8b0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 ning the transac
a8c0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 tions master-jou
a8d0: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 rnal file name.
a8e0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 VFSes that .** d
a8f0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
a900: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 signal should si
a910: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 lently ignore th
a920: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 is opcode. Appli
a930: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 cations .** shou
a940: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c ld not call [sql
a950: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
a960: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
a970: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
a980: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 o may .** disrup
a990: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 t the operation
a9a0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
a9b0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
a9c0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
a9d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
a9e0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
a9f0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 HASETWO]].** The
aa00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
aa10: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 OMMIT_PHASETWO]
aa20: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
aa30: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
aa40: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 y SQLite.** and
aa50: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
aa60: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 after a transact
aa70: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d ion has been com
aa80: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 mitted immediate
aa90: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 ly.** but before
aaa0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
aab0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 unlocked. VFSes
aac0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 that do not nee
aad0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a d this signal.**
aae0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 should silently
aaf0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 ignore this opc
ab00: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e ode. Application
ab10: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
ab20: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 l.** [sqlite3_fi
ab30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
ab40: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
ab50: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
ab60: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f isrupt the .** o
ab70: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
ab80: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
ab90: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
aba0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
abb0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
abc0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
abd0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
abe0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
abf0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 _RETRY] opcode i
ac00: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 s used to config
ac10: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a ure automatic.**
ac20: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e retry counts an
ac30: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 d intervals for
ac40: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f certain disk I/O
ac50: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 operations for
ac60: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b the.** windows [
ac70: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f VFS] in order to
ac80: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e provide robustn
ac90: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 ess in the prese
aca0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 nce of.** anti-v
acb0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 irus programs.
acc0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
acd0: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c windows VFS will
ace0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 retry file read
acf0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c ,.** file write,
ad00: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 and file delete
ad10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 operations up t
ad20: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 o 10 times, with
ad30: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 a delay.** of 2
ad40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 5 milliseconds b
ad50: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 efore the first
ad60: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 retry and with t
ad70: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 he delay increas
ad80: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 ing.** by an add
ad90: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 itional 25 milli
ada0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 seconds with eac
adb0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 h subsequent ret
adc0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ry. This.** opc
add0: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 ode allows these
ade0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 two values (10
adf0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d retries and 25 m
ae00: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 illiseconds of d
ae10: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 elay).** to be a
ae20: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 djusted. The va
ae30: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 lues are changed
ae40: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 for all databas
ae50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
ae60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
ae70: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 process. The a
ae80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
ae90: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
aea0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 of two.** integ
aeb0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 ers where the fi
aec0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 rst integer i th
aed0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e e new retry coun
aee0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
aef0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 .** integer is t
af00: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 he delay. If ei
af10: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 ther integer is
af20: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
af30: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 he setting.** is
af40: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 not changed but
af50: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 instead the pri
af60: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 or value of that
af70: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 setting is writ
af80: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ten.** into the
af90: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c array entry, all
afa0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e owing the curren
afb0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 t retry settings
afc0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 to be.** interr
afd0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 ogated. The zDb
afe0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 Name parameter i
aff0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
b000: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b010: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d NTL_PERSIST_WAL]
b020: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
b030: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
b040: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 WAL] opcode is u
b050: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
b060: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
b070: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 stent [WAL | Wri
b080: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 te Ahead Log] se
b090: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 tting. By defau
b0a0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 lt, the auxiliar
b0b0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 y.** write ahead
b0c0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 log and shared
b0d0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 memory files use
b0e0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f d for transactio
b0f0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 n control.** are
b100: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
b110: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 eleted when the
b120: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f latest connectio
b130: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 n to the databas
b140: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 e.** closes. Se
b150: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 tting persistent
b160: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 WAL mode causes
b170: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 those files to
b180: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a persist after.**
b190: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 close. Persist
b1a0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 ing the files is
b1b0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 useful when oth
b1c0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 er processes tha
b1d0: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 t do not.** have
b1e0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f write permissio
b1f0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f n on the directo
b200: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ry containing th
b210: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
b220: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 want.** to read
b230: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
b240: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e e, as the WAL an
b250: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 d shared memory
b260: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 files must exist
b270: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 .** in order for
b280: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f the database to
b290: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 be readable. T
b2a0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
b2b0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
b2c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
b2d0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
b2e0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
b2f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
b300: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
b310: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
b320: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 sable persistent
b330: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 WAL mode or 1 t
b340: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 o enable persist
b350: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e ent.** WAL mode.
b360: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
b370: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
b380: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
b390: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
b3a0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e ** WAL persisten
b3b0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a ce setting..**.*
b3c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b3d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
b3e0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 VERWRITE]].** ^T
b3f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b400: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
b410: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 RITE] opcode is
b420: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 used to set or q
b430: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 uery the.** pers
b440: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 istent "powersaf
b450: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 e-overwrite" or
b460: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 "PSOW" setting.
b470: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e The PSOW settin
b480: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 g.** determines
b490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 the [SQLITE_IOCA
b4a0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
b4b0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 WRITE] bit of th
b4c0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 e.** xDeviceChar
b4d0: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
b4e0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 ods. The fourth
b4f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
b500: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
b510: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
b520: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
b530: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
b540: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
b550: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
b560: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f to disable zero
b570: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 -damage mode or
b580: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 1 to enable zero
b590: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e -damage.** mode.
b5a0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
b5b0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
b5c0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
b5d0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
b5e0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d ** zero-damage m
b5f0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a ode setting..**.
b600: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b610: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
b620: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
b630: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
b640: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 E] opcode is inv
b650: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 oked by SQLite a
b660: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 fter opening.**
b670: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 a write transact
b680: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 ion to indicate
b690: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 that, unless it
b6a0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 is rolled back f
b6b0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f or some.** reaso
b6c0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 n, the entire da
b6d0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
b6e0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 be overwritten
b6f0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a by the current .
b700: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 ** transaction.
b710: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 This is used by
b720: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e VACUUM operation
b730: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 s..**.** <li>[[S
b740: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
b750: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 AME]].** ^The [S
b760: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
b770: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 AME] opcode can
b780: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
b790: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a n the names of.*
b7a0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e * all [VFSes] in
b7b0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 the VFS stack.
b7c0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f The names are o
b7d0: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 f all VFS shims
b7e0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c and the.** final
b7f0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 bottom-level VF
b800: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e S are written in
b810: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
b820: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
b830: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
b840: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 nd the result is
b850: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 stored in the c
b860: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a har* variable.**
b870: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 that the fourth
b880: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 parameter of [s
b890: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b8a0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f rol()] points to
b8b0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 ..** The caller
b8c0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
b8d0: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d or freeing the m
b8e0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e emory when done.
b8f0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c As with.** all
b900: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 file-control ac
b910: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 tions, there is
b920: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 no guarantee tha
b930: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 t this will actu
b940: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 ally.** do anyth
b950: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 ing. Callers sh
b960: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 ould initialize
b970: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 the char* variab
b980: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 le to a NULL.**
b990: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 pointer in case
b9a0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
b9b0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 l is not impleme
b9c0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 nted. This file
b9d0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 -control.** is i
b9e0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 ntended for diag
b9f0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e nostic use only.
ba00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
ba10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
ba20: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 ]].** ^Whenever
ba30: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 a [PRAGMA] state
ba40: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 ment is parsed,
ba50: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c an [SQLITE_FCNTL
ba60: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c _PRAGMA] .** fil
ba70: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e e control is sen
ba80: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 t to the open [s
ba90: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
baa0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e ect correspondin
bab0: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 g.** to the data
bac0: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 base file to whi
bad0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 ch the pragma st
bae0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 atement refers.
baf0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a ^The argument.**
bb00: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f to the [SQLITE_
bb10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
bb20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e le control is an
bb30: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 array of.** poi
bb40: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
bb50: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 (char**) in whi
bb60: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c ch the second el
bb70: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 ement of the arr
bb80: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d ay.** is the nam
bb90: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 e of the pragma
bba0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c and the third el
bbb0: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 ement is the arg
bbc0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 ument to the.**
bbd0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 pragma or NULL i
bbe0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 f the pragma has
bbf0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e no argument. ^
bc00: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 The handler for
bc10: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 an.** [SQLITE_FC
bc20: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
bc30: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 control can opt
bc40: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 ionally make the
bc50: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a first element.*
bc60: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 * of the char**
bc70: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 argument point t
bc80: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 o a string obtai
bc90: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
bca0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 3_mprintf()].**
bcb0: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e or the equivalen
bcc0: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e t and that strin
bcd0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 g will become th
bce0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 e result of the
bcf0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 pragma or.** the
bd00: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 error message i
bd10: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 f the pragma fai
bd20: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b ls. ^If the.** [
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
bd40: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
bd50: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
bd60: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 E_NOTFOUND], the
bd70: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 n normal .** [PR
bd80: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 AGMA] processing
bd90: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 continues. ^If
bda0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
bdb0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 TL_PRAGMA].** fi
bdc0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
bdd0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
bde0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 then the parser
bdf0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
be00: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 .** VFS has hand
be10: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 led the PRAGMA i
be20: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 tself and the pa
be30: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 rser generates a
be40: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 no-op.** prepar
be50: 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e ed statement. ^
be60: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
be70: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
be80: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
be90: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
bea0: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
beb0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
bec0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
bed0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
bee0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
bef0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
bf00: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
bf10: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
bf20: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
bf30: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
bf40: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
bf50: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
bf60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
bf70: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
bf80: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
bf90: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
bfa0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
bfb0: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
bfc0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
bfd0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
bfe0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
bff0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
c000: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c010: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
c020: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
c030: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
c040: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
c050: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
c060: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
c070: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
c080: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
c090: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
c0a0: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
c0b0: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
c0c0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
c0d0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
c0e0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
c0f0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
c100: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
c110: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
c120: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
c130: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
c140: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
c150: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
c160: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
c170: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
c180: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
c190: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
c1a0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
c1b0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
c1c0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
c1d0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
c1e0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
c1f0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
c200: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
c210: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
c220: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
c230: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
c240: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
c250: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
c260: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
c270: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
c280: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
c290: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
c2a0: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
c2b0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
c2c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
c2d0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
c2e0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
c2f0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
c310: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
c320: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
c330: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
c340: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
c350: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
c360: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
c370: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
c380: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
c390: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
c3a0: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
c3b0: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
c3c0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
c3d0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
c3e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
c3f0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
c400: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
c410: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
c420: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
c430: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
c440: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
c450: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
c460: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
c470: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
c480: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
c490: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
c4a0: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
c4b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
c4c0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
c4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
c4e0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
c4f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
c500: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
c510: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
c520: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
c530: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
c540: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
c550: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
c560: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
c570: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
c580: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
c590: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
c5a0: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
c5b0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
c5c0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
c5d0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
c5e0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
c5f0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
c600: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
c610: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
c620: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
c630: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
c640: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
c650: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
c660: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
c670: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
c680: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
c690: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
c6a0: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
c6b0: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
c6c0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
c6d0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
c6e0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
c6f0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
c700: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
c710: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
c720: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
c730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
c740: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
c750: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
c760: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
c770: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
c780: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
c790: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
c7a0: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
c7b0: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
c7c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
c7d0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
c7e0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
c7f0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
c800: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
c810: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
c820: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
c830: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
c840: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
c850: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
c860: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
c870: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
c880: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
c890: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
c8a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
c8b0: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
c8c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
c8d0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
c8e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c8f0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
c910: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
c920: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
c930: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
c940: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
c950: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
c960: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
c970: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
c980: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
c990: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
c9a0: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
c9b0: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
c9c0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
c9d0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f opened..**.** </
c9e0: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ul>.*/.#define S
c9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
ca00: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 STATE
ca10: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
ca20: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f LITE_GET_LOCKPRO
ca30: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 XYFILE
ca40: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
ca50: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_SET_LOCKPROX
ca60: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 YFILE
ca70: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
ca80: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 TE_LAST_ERRNO
ca90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
caa0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
cab0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
cac0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
cad0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
cae0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
caf0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 E 6
cb00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cb10: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
cb20: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a ER 7.
cb30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
cb40: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
cb50: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 D 8.#
cb60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
cb70: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
cb80: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 RY 9.#d
cb90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
cba0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 TL_PERSIST_WAL
cbb0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 10.#de
cbc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
cbd0: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 L_OVERWRITE
cbe0: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 11.#def
cbf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
cc00: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 _VFSNAME
cc10: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 12.#defi
cc20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
cc30: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
cc40: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e ITE 13.#defin
cc50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
cc60: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
cc70: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 14.#define
cc80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 SQLITE_FCNTL_BU
cc90: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 SYHANDLER
cca0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 15.#define
ccb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
ccc0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 PFILENAME
ccd0: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
cce0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
ccf0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 _SIZE
cd00: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 18.#define SQ
cd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
cd20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
cd30: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 19.#define SQL
cd40: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
cd50: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 VED
cd60: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 20.#define SQLI
cd70: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 TE_FCNTL_SYNC
cd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
cd90: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 21.#define SQLIT
cda0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
cdb0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 HASETWO 2
cdc0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
cdd0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a F: Mutex Handle.
cde0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 **.** The mutex
cdf0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 module within SQ
ce00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 Lite defines [sq
ce10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 lite3_mutex] to
ce20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 be an.** abstrac
ce30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 t type for a mut
ce40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 ex object. The
ce50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 SQLite core neve
ce60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 r looks.** at th
ce70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
ce80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 sentation of an
ce90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e [sqlite3_mutex].
cea0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 It only.** dea
ceb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 ls with pointers
cec0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
ced0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a _mutex] object..
cee0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 **.** Mutexes ar
cef0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 e created using
cf00: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
cf10: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 lloc()]..*/.type
cf20: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
cf30: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 e3_mutex sqlite3
cf40: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _mutex;../*.** C
cf50: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
cf60: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a rface Object.**.
cf70: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
cf80: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
cf90: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
cfa0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
cfb0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
cfc0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
cfd0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
cfe0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
cff0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
d000: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
d010: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
d020: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
d030: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a system". See.**
d040: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 the [VFS | VFS
d050: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
d060: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 or further infor
d070: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
d080: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 e value of the i
d090: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 Version field is
d0a0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 initially 1 but
d0b0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 may be larger i
d0c0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 n.** future vers
d0d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ions of SQLite.
d0e0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c Additional fiel
d0f0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
d100: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 ed to this.** ob
d110: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 ject when the iV
d120: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 ersion value is
d130: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 increased. Note
d140: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 that the struct
d150: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ure.** of the sq
d160: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
d170: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
d180: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 transaction betw
d190: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 een.** SQLite ve
d1a0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 rsion 3.5.9 and
d1b0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 3.6.0 and yet th
d1c0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
d1d0: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 was not.** modi
d1e0: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fied..**.** The
d1f0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 szOsFile field i
d200: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
d210: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 e subclassed [sq
d220: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 lite3_file].** s
d230: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 tructure used by
d240: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 this VFS. mxPa
d250: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 thname is the ma
d260: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a ximum length of.
d270: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e ** a pathname in
d280: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a this VFS..**.**
d290: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 Registered sqli
d2a0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 te3_vfs objects
d2b0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 are kept on a li
d2c0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 nked list formed
d2d0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 by.** the pNext
d2e0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b pointer. The [
d2f0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
d300: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b ster()].** and [
d310: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
d320: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 gister()] interf
d330: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 aces manage this
d340: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 list.** in a th
d350: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 read-safe way.
d360: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
d370: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 _find()] interfa
d380: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 ce.** searches t
d390: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 he list. Neithe
d3a0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
d3b0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 n code nor the V
d3c0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 FS.** implementa
d3d0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 tion should use
d3e0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
d3f0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 r..**.** The pNe
d400: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 xt field is the
d410: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 only field in th
d420: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
d430: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
d440: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 SQLite will ever
d450: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 modify. SQLite
d460: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 will only acces
d470: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 s.** or modify t
d480: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 his field while
d490: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 holding a partic
d4a0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 ular static mute
d4b0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 x..** The applic
d4c0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
d4d0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 er modify anythi
d4e0: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 ng within the sq
d4f0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a lite3_vfs.** obj
d500: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a ect once the obj
d510: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 ect has been reg
d520: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 istered..**.** T
d530: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 he zName field h
d540: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 olds the name of
d550: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e the VFS module.
d560: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a The name must.
d570: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 ** be unique acr
d580: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 oss all VFS modu
d590: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c les..**.** [[sql
d5a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d ite3_vfs.xOpen]]
d5b0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 .** ^SQLite guar
d5c0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
d5d0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
d5e0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 ter to xOpen.**
d5f0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c is either a NULL
d600: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 pointer or stri
d610: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ng obtained.** f
d620: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d rom xFullPathnam
d630: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 e() with an opti
d640: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 onal suffix adde
d650: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 d..** ^If a suff
d660: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 ix is added to t
d670: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
d680: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a ameter, it will.
d690: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 ** consist of a
d6a0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 single "-" chara
d6b0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 cter followed by
d6c0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a no more than.**
d6d0: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 11 alphanumeric
d6e0: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 and/or "-" char
d6f0: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 acters..** ^SQLi
d700: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 te further guara
d710: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 ntees that.** th
d720: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
d730: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 valid and uncha
d740: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 nged until xClos
d750: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 e() is.** called
d760: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 . Because of the
d770: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
d780: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ce,.** the [sqli
d790: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 te3_file] can sa
d7a0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 fely store a poi
d7b0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 nter to the.** f
d7c0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 ilename if it ne
d7d0: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 eds to remember
d7e0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 the filename for
d7f0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a some reason..**
d800: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d If the zFilenam
d810: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
d820: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 Open is a NULL p
d830: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 ointer then xOpe
d840: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 n.** must invent
d850: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 its own tempora
d860: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 ry name for the
d870: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 file. ^Whenever
d880: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 the .** xFilena
d890: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
d8a0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 NULL it will als
d8b0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 o be the case th
d8c0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 at the.** flags
d8d0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 parameter will i
d8e0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
d8f0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
d900: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c E]..**.** The fl
d910: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
d920: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 xOpen() includes
d930: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e all bits set in
d940: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 .** the flags ar
d950: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
d960: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 e3_open_v2()].
d970: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f Or if [sqlite3_o
d980: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 pen()].** or [sq
d990: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
d9a0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c is used, then fl
d9b0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 ags includes at
d9c0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 least.** [SQLITE
d9d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
d9e0: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
d9f0: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 CREATE]. .** If
da00: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
da10: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
da20: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
da30: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
da40: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
da50: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
da60: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
da70: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
da80: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 t..**.** ^(SQLit
da90: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 e will also add
daa0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
dab0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
dac0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c e xOpen().** cal
dad0: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 l, depending on
dae0: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 the object being
daf0: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c opened:.**.** <
db00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 ul>.** <li> [SQ
db10: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
db20: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
db30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
db40: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
db50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
db60: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b P_DB].** <li> [
db70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
db80: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
db90: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
dba0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a TRANSIENT_DB].**
dbb0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
dbc0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a PEN_SUBJOURNAL].
dbd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
dbe0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
dbf0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
dc00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d SQLITE_OPEN_WAL]
dc10: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
dc20: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 * The file I/O i
dc30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
dc40: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 n use the object
dc50: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a type flags to.*
dc60: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 * change the way
dc70: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
dc80: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
dc90: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
dca0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
dcb0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
dcc0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
dcd0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 rollback might
dce0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e make.** the open
dcf0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 of a journal fi
dd00: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 le a no-op. Wri
dd10: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 tes to this jour
dd20: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 nal would.** als
dd30: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 o be no-ops, and
dd40: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 any attempt to
dd50: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c read the journal
dd60: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a would return.**
dd70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 SQLITE_IOERR.
dd80: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 Or the implement
dd90: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f ation might reco
dda0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 gnize that a dat
ddb0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 abase.** file wi
ddc0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 ll be doing page
ddd0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 -aligned sector
dde0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
ddf0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 in a random.**
de00: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 order and set up
de10: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 its I/O subsyst
de20: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a em accordingly..
de30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 **.** SQLite mig
de40: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ht also add one
de50: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
de60: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
de70: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a pen method:.**.*
de80: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
de90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
dea0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
deb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
dec0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
ded0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ul>.**.** The [S
dee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
def0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d EONCLOSE] flag m
df00: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
df10: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 ould be.** delet
df20: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c ed when it is cl
df30: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c osed. ^The [SQL
df40: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
df50: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
df60: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
df70: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 databases and th
df80: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 eir journals, tr
df90: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 ansient.** datab
dfa0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 ases, and subjou
dfb0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rnals..**.** ^Th
dfc0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
dfd0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 XCLUSIVE] flag i
dfe0: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e s always used in
dff0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 conjunction.**
e000: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
e010: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c _OPEN_CREATE] fl
e020: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f ag, which are bo
e030: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 th directly.** a
e040: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 nalogous to the
e050: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 O_EXCL and O_CRE
e060: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 AT flags of the
e070: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 POSIX open().**
e080: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 API. The SQLITE
e090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
e0a0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 flag, when paire
e0b0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
e0c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
e0d0: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e E, is used to in
e0e0: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 dicate that file
e0f0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a should always.*
e100: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e * be created, an
e110: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 d that it is an
e120: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 error if it alre
e130: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 ady exists..** I
e140: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 t is <i>not</i>
e150: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
e160: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
e170: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 be opened .** f
e180: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 or exclusive acc
e190: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c ess..**.** ^At l
e1a0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 east szOsFile by
e1b0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 tes of memory ar
e1c0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 e allocated by S
e1d0: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 QLite.** to hold
e1e0: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 the [sqlite3_f
e1f0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 ile] structure p
e200: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 assed as the thi
e210: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 rd.** argument t
e220: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f o xOpen. The xO
e230: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 pen method does
e240: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 not have to.** a
e250: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 llocate the stru
e260: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 cture; it should
e270: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e just fill it in
e280: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 . Note that.**
e290: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
e2a0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 must set the sq
e2b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
e2c0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a ods to either.**
e2d0: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 a valid [sqlite
e2e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
e2f0: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e ject or to NULL.
e300: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a xOpen must do.
e310: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 ** this even if
e320: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 the open fails.
e330: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 SQLite expects
e340: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 that the sqlite3
e350: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a _file.pMethods.*
e360: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 * element will b
e370: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f e valid after xO
e380: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 pen returns rega
e390: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 rdless of the su
e3a0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c ccess.** or fail
e3b0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e ure of the xOpen
e3c0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 call..**.** [[s
e3d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 qlite3_vfs.xAcce
e3e0: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 ss]].** ^The fla
e3f0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
e400: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 Access() may be
e410: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 [SQLITE_ACCESS_E
e420: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 XISTS].** to tes
e430: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 t for the existe
e440: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f nce of a file, o
e450: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
e460: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a _READWRITE] to.*
e470: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 * test whether a
e480: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
e490: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
e4a0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
e4b0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 S_READ].** to te
e4c0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
e4d0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 e is at least re
e4e0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 adable. The fi
e4f0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
e500: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
e510: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 ^SQLite will alw
e520: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
e530: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
e540: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
e550: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
e560: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
e570: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 The exact size
e580: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
e590: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
e5a0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
e5b0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
e5c0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 methods. If the
e5d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
e5e0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
e5f0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
e600: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
e610: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
e620: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
e630: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
e640: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
e650: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
e660: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
e670: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
e680: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
e690: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
e6a0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
e6b0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
e6c0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
e6d0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
e6e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 xCurrentTime(),
e6f0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
e700: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 Int64().** inter
e710: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 faces are not st
e720: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
e730: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
e740: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
e750: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
e760: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
e770: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
e780: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
e790: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
e7a0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
e7b0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
e7c0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
e7d0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
e7e0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
e7f0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
e800: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
e810: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
e820: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
e830: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
e840: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
e850: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
e860: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
e870: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
e880: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
e890: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
e8a0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
e8b0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
e8c0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
e8d0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
e8e0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
e8f0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 nd time as.** a
e900: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
e910: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 alue..** ^The xC
e920: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
e930: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
e940: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c , as an integer,
e950: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 the Julian.** D
e960: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 ay Number multip
e970: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 lied by 86400000
e980: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 (the number of
e990: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 milliseconds in
e9a0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 .** a 24-hour da
e9b0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 y). .** ^SQLite
e9c0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 will use the xC
e9d0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
e9e0: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 ) method to get
e9f0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 the current.** d
ea00: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 ate and time if
ea10: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 that method is a
ea20: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 vailable (if iVe
ea30: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a rsion is 2 or .*
ea40: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 * greater and th
ea50: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 e function point
ea60: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 er is not NULL)
ea70: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 and will fall ba
ea80: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e ck.** to xCurren
ea90: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 tTime() if xCurr
eaa0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 entTimeInt64() i
eab0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
eac0: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 *.** ^The xSetSy
ead0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 stemCall(), xGet
eae0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e SystemCall(), an
eaf0: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c d xNestSystemCal
eb00: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a l() interfaces.*
eb10: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 * are not used b
eb20: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 y the SQLite cor
eb30: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e e. These option
eb40: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
eb50: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 e provided.** by
eb60: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 some VFSes to f
eb70: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e acilitate testin
eb80: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 g of the VFS cod
eb90: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 e. By overriding
eba0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c .** system call
ebb0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 s with functions
ebc0: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 under its contr
ebd0: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 ol, a test progr
ebe0: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 am can.** simula
ebf0: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 te faults and er
ec00: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 ror conditions t
ec10: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 hat would otherw
ec20: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 ise be difficult
ec30: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c .** or impossibl
ec40: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 e to induce. Th
ec50: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 e set of system
ec60: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 calls that can b
ec70: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 e overridden.**
ec80: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 varies from one
ec90: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 VFS to another,
eca0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 and from one ver
ecb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 sion of the same
ecc0: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e VFS to the.** n
ecd0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
ece0: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 ns that use thes
ecf0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 e interfaces mus
ed00: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f t be prepared fo
ed10: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 r any.** or all
ed20: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 of these interfa
ed30: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f ces to be NULL o
ed40: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 r for their beha
ed50: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a vior to change.*
ed60: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 * from one relea
ed70: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 se to the next.
ed80: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 Applications mu
ed90: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 st not attempt t
eda0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 o access.** any
edb0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 of these methods
edc0: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e if the iVersion
edd0: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c of the VFS is l
ede0: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 ess than 3..*/.t
edf0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
ee00: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
ee10: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 3_vfs;.typedef v
ee20: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 oid (*sqlite3_sy
ee30: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 scall_ptr)(void)
ee40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
ee50: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 _vfs {. int iVe
ee60: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 rsion;
ee70: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 /* Structure v
ee80: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 ersion number (c
ee90: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 urrently 3) */.
eea0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
eeb0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
eec0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
eed0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
eee0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
eef0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
ef00: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
ef10: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
ef20: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
ef30: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
ef40: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
ef50: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
ef60: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
ef70: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
ef80: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
ef90: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
efa0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
efb0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
efc0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
efd0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
efe0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
eff0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
f000: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
f010: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
f020: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
f030: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
f040: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
f050: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
f060: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
f070: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
f080: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
f090: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
f0a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
f0b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
f0c0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
f0d0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
f0e0: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f thname)(sqlite3_
f0f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
f100: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 *zName, int nOu
f110: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a t, char *zOut);.
f120: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 void *(*xDlOpe
f130: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
f140: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
f150: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 lename);. void
f160: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 (*xDlError)(sqli
f170: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
f180: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d yte, char *zErrM
f190: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a sg);. void (*(*
f1a0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
f1b0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
f1c0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
f1d0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 )(void);. void
f1e0: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 (*xDlClose)(sqli
f1f0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 te3_vfs*, void*)
f200: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f ;. int (*xRando
f210: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 mness)(sqlite3_v
f220: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
f230: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 char *zOut);. i
f240: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c nt (*xSleep)(sql
f250: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
f260: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 icroseconds);.
f270: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
f280: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
f290: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e , double*);. in
f2a0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f t (*xGetLastErro
f2b0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
f2c0: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 int, char *);.
f2d0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
f2e0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
f2f0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
f300: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
f310: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 ject. ** defini
f320: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 tion. Those tha
f330: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 t follow are add
f340: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 ed in version 2
f350: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 or later. */.
f360: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
f370: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 meInt64)(sqlite3
f380: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 _vfs*, sqlite3_i
f390: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a nt64*);. /*. *
f3a0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
f3b0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
f3c0: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 ons 1 and 2 of t
f3d0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
f3e0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 ject.. ** Those
f3f0: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 below are for v
f400: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 ersion 3 and gre
f410: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 ater.. */. int
f420: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c (*xSetSystemCal
f430: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
f440: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
f450: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 me, sqlite3_sysc
f460: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 all_ptr);. sqli
f470: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 te3_syscall_ptr
f480: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xGetSystemCall
f490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
f4a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
f4b0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 e);. const char
f4c0: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 *(*xNextSystemC
f4d0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
f4e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
f4f0: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a Name);. /*. **
f500: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
f510: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
f520: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f ns 1 through 3 o
f530: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
f540: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 object.. ** Ne
f550: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
f560: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
f570: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
f580: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
f590: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
f5a0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
f5b0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a is happens. . *
f5c0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
f5d0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
f5e0: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
f5f0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
f600: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
f610: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 ants can be used
f620: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 as the third pa
f630: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
f640: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
f650: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
f660: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 vfs] object. Th
f670: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 ey determine.**
f680: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 what kind of per
f690: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 missions the xAc
f6a0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c cess method is l
f6b0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 ooking for..** W
f6c0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
f6d0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
f6e0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
f6f0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 simply checks wh
f700: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 ether the file e
f710: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 xists..** With S
f720: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
f730: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 DWRITE, the xAcc
f740: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
f750: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
f760: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 named directory
f770: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c is both readabl
f780: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a e and writable.*
f790: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 * (in other word
f7a0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 s, if files can
f7b0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 be added, remove
f7c0: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 d, and renamed w
f7d0: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 ithin.** the dir
f7e0: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 ectory)..** The
f7f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
f800: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 ADWRITE constant
f810: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 is currently us
f820: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a ed only by the.*
f830: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 * [temp_store_di
f840: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c rectory pragma],
f850: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 though this cou
f860: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ld change in a f
f870: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
f880: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 of SQLite..** W
f890: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
f8a0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 S_READ, the xAcc
f8b0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
f8c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
f8d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
f8e0: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 e. The SQLITE_A
f8f0: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 CCESS_READ const
f900: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e ant is.** curren
f910: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 tly unused, thou
f920: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 gh it might be u
f930: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 sed in a future
f940: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
f950: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
f960: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
f970: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
f980: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
f990: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f _READWRITE 1 /
f9a0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 * Used by PRAGMA
f9b0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 temp_store_dire
f9c0: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ctory */.#define
f9d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
f9e0: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 EAD 2 /*
f9f0: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a Unused */../*.**
fa00: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
fa10: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 for the xShmLoc
fa20: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a k VFS method.**.
fa30: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
fa40: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
fa50: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f e the various lo
fa60: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 cking operations
fa70: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 .** allowed by t
fa80: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
fa90: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 od of [sqlite3_i
faa0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 o_methods]. The
fab0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 .** following ar
fac0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c e the only legal
fad0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 combinations of
fae0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a flags to the.**
faf0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
fb00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
fb10: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
fb20: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 _LOCK | SQLITE_S
fb30: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 HM_SHARED.** <li
fb40: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
fb50: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
fb60: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 EXCLUSIVE.** <li
fb70: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e > SQLITE_SHM_UN
fb80: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
fb90: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
fba0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
fbb0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
fbc0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f _EXCLUSIVE.** </
fbd0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 ul>.**.** When u
fbe0: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 nlocking, the sa
fbf0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 me SHARED or EXC
fc00: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 LUSIVE flag must
fc10: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a be supplied as.
fc20: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 ** was given no
fc30: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
fc40: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 g lock. .**.**
fc50: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 The xShmLock met
fc60: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 hod can transiti
fc70: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 on between unloc
fc80: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f ked and SHARED o
fc90: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c r.** between unl
fca0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 ocked and EXCLUS
fcb0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 IVE. It cannot
fcc0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
fcd0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 en SHARED.** and
fce0: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 EXCLUSIVE..*/.#
fcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
fd00: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 M_UNLOCK 1
fd10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
fd20: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 SHM_LOCK
fd30: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
fd40: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 E_SHM_SHARED
fd50: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
fd60: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
fd70: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 E 8../*.** CA
fd80: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 PI3REF: Maximum
fd90: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a xShmLock index.*
fda0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
fdb0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c k method on [sql
fdc0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
fdd0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a may use values.
fde0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ** between 0 and
fdf0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e this upper boun
fe00: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 d as its "offset
fe10: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 " argument..** T
fe20: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 he SQLite core w
fe30: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 ill never attemp
fe40: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 t to acquire or
fe50: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 release a.** loc
fe60: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 k outside of thi
fe70: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 s range.*/.#defi
fe80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c ne SQLITE_SHM_NL
fe90: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f OCK 8.../
fea0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
feb0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
fec0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
fed0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
fee0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
fef0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
ff00: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
ff10: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
ff20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
ff30: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
ff40: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
ff50: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
ff60: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
ff70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ff80: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
ff90: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
ffa0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
ffb0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
ffc0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
ffd0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
ffe0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
fff0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
10000 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
10010 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
10020 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
10030 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
10040 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
10050 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
10060 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10070 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
10080 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
10090 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
100a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
100b0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
100c0 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
100d0 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
100e0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
100f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
10100 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
10110 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
10120 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
10130 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
10140 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
10150 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
10160 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
10170 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10180 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
10190 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
101a0 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
101b0 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
101c0 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
101d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
101e0 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
101f0 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
10200 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
10210 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
10220 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10230 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
10240 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
10250 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
10260 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
10270 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
10280 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
10290 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
102a0 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
102b0 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
102c0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
102d0 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
102e0 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
102f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
10300 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
10310 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
10320 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
10330 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
10340 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
10350 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
10360 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
10370 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
10380 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
10390 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
103a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
103b0 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
103c0 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
103d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
103e0 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
103f0 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
10400 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
10410 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10420 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
10430 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
10440 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10450 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
10460 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
10470 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
10480 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
10490 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
104a0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
104b0 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
104c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
104d0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
104e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
104f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
10500 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
10510 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
10520 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
10530 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
10540 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
10550 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
10560 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
10570 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
10580 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
10590 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
105a0 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
105b0 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
105c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
105d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
105e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
105f0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
10600 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
10610 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
10620 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
10630 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
10640 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
10650 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
10660 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
10670 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
10680 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
10690 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
106a0 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
106b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
106c0 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
106d0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
106e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
106f0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
10700 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
10710 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
10720 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
10730 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
10740 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
10750 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
10760 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
10770 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
10780 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
10790 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
107a0 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
107b0 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
107c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
107d0 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
107e0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
107f0 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
10800 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10810 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
10820 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
10830 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
10840 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
10850 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
10860 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
10870 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
10880 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
10890 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
108a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
108b0 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
108c0 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
108d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
108e0 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
108f0 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
10900 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
10910 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
10920 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
10930 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
10940 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
10950 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
10960 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
10970 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
10980 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
10990 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
109a0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
109b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
109c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
109d0 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
109e0 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
109f0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
10a00 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
10a10 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
10a20 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
10a30 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
10a40 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
10a50 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
10a60 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
10a70 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
10a80 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
10a90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
10aa0 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
10ab0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
10ac0 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
10ad0 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
10ae0 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
10af0 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
10b00 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
10b10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
10b20 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
10b30 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
10b40 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
10b50 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
10b60 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
10b70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
10b80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
10b90 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
10ba0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10bb0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
10bc0 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
10bd0 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
10be0 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
10bf0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
10c00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
10c10 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
10c20 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
10c30 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
10c40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
10c50 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
10c60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
10c70 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
10c80 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
10c90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
10ca0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10cb0 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
10cc0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
10cd0 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
10ce0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
10cf0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
10d00 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
10d10 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
10d20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
10d30 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
10d40 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
10d50 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
10d60 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
10d70 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
10d80 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
10d90 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
10da0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
10db0 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
10dc0 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
10dd0 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
10de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
10df0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
10e00 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
10e10 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
10e20 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
10e30 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
10e40 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
10e50 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
10e60 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
10e70 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
10e80 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
10e90 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
10ea0 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
10eb0 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
10ec0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
10ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 int sqlite3_init
10ee0 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 ialize(void);.SQ
10ef0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
10f00 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f ite3_shutdown(vo
10f10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
10f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 int sqlite3_os_i
10f30 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nit(void);.SQLIT
10f40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
10f50 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
10f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10f70 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
10f80 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a SQLite Library.
10f90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
10fa0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
10fb0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
10fc0 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 make global conf
10fd0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
10fe0 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 nges to SQLite i
10ff0 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 n order to tune
11000 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 SQLite to the sp
11010 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a ecific needs of.
11020 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
11030 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 on. The default
11040 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 configuration i
11050 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f s recommended fo
11060 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 r most.** applic
11070 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 ations and so th
11080 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 is routine is us
11090 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 ually not necess
110a0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 ary. It is.** p
110b0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f rovided to suppo
110c0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 rt rare applicat
110d0 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 ions with unusua
110e0 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 l needs..**.** T
110f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
11100 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
11110 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e not threadsafe.
11120 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
11130 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 n.** must insure
11140 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 that no other S
11150 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
11160 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 are invoked by
11170 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 other.** threads
11180 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 while sqlite3_c
11190 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 onfig() is runni
111a0 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 ng. Furthermore
111b0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
111c0 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ().** may only b
111d0 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 e invoked prior
111e0 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 to library initi
111f0 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a alization using.
11200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ** [sqlite3_init
11210 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 ialize()] or aft
11220 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b er shutdown by [
11230 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11240 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ()]..** ^If sqli
11250 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
11260 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
11270 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11280 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a ()] and before.*
11290 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
112a0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 own()] then it w
112b0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ill return SQLIT
112c0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 E_MISUSE..** Not
112d0 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 e, however, that
112e0 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 ^sqlite3_config
112f0 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 () can be called
11300 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a as part of the.
11310 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
11320 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 n of an applicat
11330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c ion-defined [sql
11340 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e ite3_os_init()].
11350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
11360 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
11370 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
11380 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b an integer.** [
11390 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
113a0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 tion] that deter
113b0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 mines.** what pr
113c0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 operty of SQLite
113d0 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 is to be config
113e0 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e ured. Subsequen
113f0 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 t arguments.** v
11400 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
11410 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 the [configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 ion option].** i
11430 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
11440 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 ment..**.** ^Whe
11450 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f n a configuratio
11460 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c n option is set,
11470 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11480 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ) returns [SQLIT
11490 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 E_OK]..** ^If th
114a0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e e option is unkn
114b0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 own or SQLite is
114c0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 unable to set t
114d0 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 he option.** the
114e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 n this routine r
114f0 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 eturns a non-zer
11500 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a o [error code]..
11510 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
11520 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 t sqlite3_config
11530 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
11540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
11550 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 figure database
11560 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a connections.**.*
11570 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
11580 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
11590 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d ace is used to m
115a0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ake configuratio
115b0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
115c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
115d0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e ection]. The in
115e0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c terface is simil
115f0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ar to.** [sqlite
11600 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 3_config()] exce
11610 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e pt that the chan
11620 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 ges apply to a s
11630 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 ingle.** [databa
11640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
11650 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 specified in the
11660 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 first argument)
11670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
11680 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
11690 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
116a0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 (D,V,...) is th
116b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 e.** [SQLITE_DBC
116c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
116d0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
116e0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 verb] - an integ
116f0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 er code .** that
11700 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 indicates what
11710 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 aspect of the [d
11720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11730 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e on] is being con
11740 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 figured..** Subs
11750 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
11760 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
11770 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 on the configura
11780 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a tion verb..**.**
11790 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 ^Calls to sqlit
117a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 e3_db_config() r
117b0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 eturn SQLITE_OK
117c0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a if and only if.*
117d0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f * the call is co
117e0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 nsidered success
117f0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
11800 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 PI int sqlite3_d
11810 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 b_config(sqlite3
11820 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b *, int op, ...);
11830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11840 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
11850 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a ion Routines.**.
11860 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
11870 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 f this object de
11880 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
11890 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 ace between SQLi
118a0 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 te.** and low-le
118b0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
118c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
118d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 **.** This objec
118e0 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c t is used in onl
118f0 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 y one place in t
11900 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 he SQLite interf
11910 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ace..** A pointe
11920 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
11930 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
11940 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
11950 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
11960 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 onfig()] when th
11970 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
11980 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 option is.** [SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
119a0 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 OC] or [SQLITE_C
119b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
119c0 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 . .** By creati
119d0 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f ng an instance o
119e0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a f this object.**
119f0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 and passing it
11a00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
11a10 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
11a20 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 IG_MALLOC]).** d
11a30 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
11a40 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ion, an applicat
11a50 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 ion can specify
11a60 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
11a70 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
11a80 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f ion subsystem fo
11a90 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 r SQLite to use
11aa0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a for all of its.*
11ab0 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 * dynamic memory
11ac0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
11ad0 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
11ae0 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 omes with severa
11af0 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f l [built-in memo
11b00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a ry allocators].*
11b10 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 * that are perfe
11b20 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
11b30 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
11b40 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
11b50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
11b60 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
11b70 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
11b80 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
11b90 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
11ba0 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
11bb0 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
11bc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
11bd0 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
11be0 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
11bf0 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
11c00 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
11c10 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
11c20 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
11c30 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
11c40 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
11c50 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
11c60 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
11c70 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
11c80 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
11c90 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
11ca0 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
11cb0 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
11cc0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
11cd0 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 Malloc, xRealloc
11ce0 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 , and xFree meth
11cf0 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
11d00 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
11d10 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e (), realloc() an
11d20 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
11d30 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
11d40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
11d50 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
11d60 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 ntees that the s
11d70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
11d80 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 o.** xRealloc is
11d90 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 always a value
11da0 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 returned by a pr
11db0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 ior call to xRou
11dc0 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a ndup..**.** xSiz
11dd0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
11de0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
11df0 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
11e00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
11e10 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
11e20 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
11e30 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
11e40 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
11e50 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
11e60 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
11e70 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
11e80 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
11e90 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
11ea0 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
11eb0 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
11ec0 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
11ed0 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
11ee0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11ef0 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
11f00 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
11f10 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
11f20 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
11f30 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
11f40 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
11f50 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
11f60 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
11f70 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
11f80 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
11f90 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
11fa0 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
11fb0 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
11fc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11fd0 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
11fe0 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
11ff0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
12000 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
12010 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
12020 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
12030 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
12040 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
12050 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
12060 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
12070 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
12080 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
12090 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
120a0 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
120b0 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 allocator. For
120c0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 example,.** it
120d0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 might allocate a
120e0 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 ny require mutex
120f0 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 es or initialize
12100 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a internal data.*
12110 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 * structures. T
12120 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 he xShutdown met
12130 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 hod is invoked (
12140 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a indirectly) by.*
12150 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
12160 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c own()] and shoul
12170 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 d deallocate any
12180 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 resources acqui
12190 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e red.** by xInit.
121a0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 The pAppData p
121b0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 ointer is used a
121c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
121d0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 eter to.** xInit
121e0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a and xShutdown..
121f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c **.** SQLite hol
12200 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d ds the [SQLITE_M
12210 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
12220 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 ER] mutex when i
12230 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 t invokes.** the
12240 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 xInit method, s
12250 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 o the xInit meth
12260 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 od need not be t
12270 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a hreadsafe. The.
12280 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 ** xShutdown met
12290 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c hod is only call
122a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
122b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 _shutdown()] so
122c0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e it does.** not n
122d0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 eed to be thread
122e0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f safe either. Fo
122f0 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 r all other meth
12300 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 ods, SQLite.** h
12310 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
12320 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
12330 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 M] mutex as long
12340 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 as the.** [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
12360 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 TUS] configurati
12370 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 on option is tur
12380 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a ned on (which.**
12390 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c it is by defaul
123a0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 t) and so the me
123b0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 thods are automa
123c0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a tically serializ
123d0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 ed..** However,
123e0 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 if [SQLITE_CONFI
123f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 G_MEMSTATUS] is
12400 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 disabled, then t
12410 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 he other.** meth
12420 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 ods must be thre
12430 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d adsafe or else m
12440 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 ake their own ar
12450 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a rangements for.*
12460 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e * serialization.
12470 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
12480 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ll never invoke
12490 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 xInit() more tha
124a0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 n once without a
124b0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a n intervening.**
124c0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f call to xShutdo
124d0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 wn()..*/.typedef
124e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
124f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
12500 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
12510 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
12520 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
12530 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 void *(*xMalloc)
12540 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
12550 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
12560 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
12570 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 void (*xFree)(
12580 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
12590 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
125a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
125b0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f void *(*xReallo
125c0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
125d0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
125e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
125f0 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 (*xSize)(void*)
12600 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
12610 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
12620 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
12630 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e */. int (*xRoun
12640 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
12650 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
12660 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
12670 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
12680 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 */. int (*xInit
12690 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
126a0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
126b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
126c0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
126d0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
126e0 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
126f0 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
12700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
12710 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
12720 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
12730 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
12740 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
12750 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
12760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12770 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
12780 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f Options.** KEYWO
12790 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 RDS: {configurat
127a0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a ion option}.**.*
127b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
127c0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
127d0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
127e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
127f0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
12800 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
12810 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
12820 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
12830 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
12840 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
12850 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12860 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
12870 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
12880 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
12890 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
128a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
128b0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
128c0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
128d0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
128e0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
128f0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
12900 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 e3_config()] to
12910 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
12920 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
12930 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
12940 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
12950 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
12960 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
12970 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
12980 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
12990 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
129a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
129b0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
129c0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
129d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
129e0 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 INGLETHREAD]] <d
129f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12a00 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
12a10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
12a20 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
12a30 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
12a40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
12a50 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
12a60 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 ding mode] to Si
12a70 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e ngle-thread. In
12a80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
12a90 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c disables.** all
12aa0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 mutexing and pu
12ab0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 ts SQLite into a
12ac0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 mode where it c
12ad0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a an only be used.
12ae0 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ** by a single t
12af0 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c hread. ^If SQL
12b00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12b10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
12b20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
12b30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
12b40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
12b50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
12b60 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
12b70 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 ible to change t
12b80 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
12b90 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 de] from its def
12ba0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 ault.** value of
12bb0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 Single-thread a
12bc0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 nd so [sqlite3_c
12bd0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
12be0 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 turn .** [SQLITE
12bf0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
12c00 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 d with the SQLIT
12c10 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
12c20 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 HREAD.** configu
12c30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
12c40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12c50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
12c60 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
12c70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
12c80 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
12c90 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
12ca0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
12cb0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
12cc0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
12cd0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
12ce0 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 de] to Multi-thr
12cf0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
12d00 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
12d10 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e s.** mutexing on
12d20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12d30 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
12d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
12d50 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 objects..** The
12d60 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 application is r
12d70 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 esponsible for s
12d80 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 erializing acces
12d90 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 s to.** [databas
12da0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
12db0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
12dc0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f tements]. But o
12dd0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 ther mutexes.**
12de0 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 are enabled so t
12df0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
12e00 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 be safe to use i
12e10 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
12e20 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e ed.** environmen
12e30 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 t as long as no
12e40 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 two threads atte
12e50 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 mpt to use the s
12e60 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ame.** [database
12e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
12e80 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 the same time.
12e90 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
12ea0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
12eb0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
12ec0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
12ed0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
12ee0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12ef0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12f00 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
12f10 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 et the Multi-thr
12f20 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
12f30 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
12f40 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12f50 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
12f60 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
12f70 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
12f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
12f90 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 LTITHREAD config
12fa0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
12fb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
12fd0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 LIZED]] <dt>SQLI
12fe0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12ff0 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZED</dt>.** <dd
13000 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
13010 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
13020 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
13030 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
13040 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
13050 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 e] to Serialized
13060 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
13070 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e , this option en
13080 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
13090 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 exes including t
130a0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 he recursive.**
130b0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 mutexes on [data
130c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
130d0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
130e0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
130f0 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f s..** In this mo
13100 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 de (which is the
13110 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 default when SQ
13120 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
13130 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 with.** [SQLITE
13140 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 _THREADSAFE=1])
13150 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
13160 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 ry will itself s
13170 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a erialize access.
13180 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 ** to [database
13190 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
131a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
131b0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 ments] so that t
131c0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
131d0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 n is free to use
131e0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
131f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13200 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b or the.** same [
13210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
13220 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 nt] in different
13230 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
13240 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 same time..** ^I
13250 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
13260 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
13270 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
13280 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
13290 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
132a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
132b0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
132c0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
132d0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 the Serialized
132e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
132f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
13300 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
13310 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
13320 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
13330 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
13340 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
13350 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 IZED configurati
13360 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
13370 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
13380 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c ONFIG_MALLOC]] <
13390 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
133a0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
133b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
133c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
133d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
133e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
133f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
13400 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
13410 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
13420 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
13430 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
13440 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
13450 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
13460 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
13470 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
13480 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 n place of.** th
13490 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
134a0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 ion routines bui
134b0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
134c0 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a ^ ^SQLite makes.
134d0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ** its own priva
134e0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 te copy of the c
134f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
13500 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
13510 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ds] structure.**
13520 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c before the [sql
13530 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 ite3_config()] c
13540 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 all returns.</dd
13550 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13560 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
13570 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 C]] <dt>SQLITE_C
13580 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c ONFIG_GETMALLOC<
13590 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
135a0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
135b0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
135c0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
135d0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
135e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
135f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13600 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
13610 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
13620 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
13630 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
13640 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
13650 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
13660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13670 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 outines.)^.** Th
13680 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
13690 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
136a0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 d the default me
136b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
136c0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
136d0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 a wrapper that
136e0 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f simulations memo
136f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
13700 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 ilure or.** trac
13710 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c ks memory usage,
13720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f for example. </
13730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13740 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
13750 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TUS]] <dt>SQLITE
13760 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
13770 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
13780 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13790 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
137a0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
137b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
137c0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
137d0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
137e0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
137f0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
13800 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
13810 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 tatistics. ^(Whe
13820 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
13830 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
13840 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 re disabled, the
13850 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 .** following S
13860 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
13870 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
13880 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
13890 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
138a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
138b0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
138c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
138d0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
138e0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
138f0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
13900 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
13910 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
13920 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
13930 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
13940 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
13950 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
13960 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
13970 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
13980 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
13990 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
139a0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
139b0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
139c0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
139d0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
139e0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
139f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13a00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
13a10 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f CH]] <dt>SQLITE_
13a20 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
13a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
13a40 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
13a50 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
13a60 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
13a70 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
13a80 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d r.** scratch mem
13a90 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 ory. There are
13aa0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a three arguments:
13ab0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 A pointer an 8
13ac0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 -byte.** aligned
13ad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 memory buffer f
13ae0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 rom which the sc
13af0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
13b00 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 s will be.** dra
13b10 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 wn, the size of
13b20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c each scratch all
13b30 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a ocation (sz),.**
13b40 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d and the maximum
13b50 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 number of scrat
13b60 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 ch allocations (
13b70 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 N). The sz.** a
13b80 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
13b90 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 a multiple of 16
13ba0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
13bb0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
13bc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
13bd0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
13be0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c uffer.** of at l
13bf0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
13c00 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
13c10 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e QLite will use n
13c20 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 o more than two
13c30 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 scratch buffers
13c40 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a per thread. So.
13c50 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 ** N should be s
13c60 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 et to twice the
13c70 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d expected maximum
13c80 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 number of threa
13c90 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ds..** ^SQLite w
13ca0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 ill never requir
13cb0 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 e a scratch buff
13cc0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 er that is more
13cd0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 than 6.** times
13ce0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
13cf0 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 e size. ^If SQLi
13d00 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 te needs needs a
13d10 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 dditional.** scr
13d20 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f atch memory beyo
13d30 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
13d40 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 ded by this conf
13d50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13d60 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 , then .** [sqli
13d70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 te3_malloc()] wi
13d80 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 ll be used to ob
13d90 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 tain the memory
13da0 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a needed.</dd>.**.
13db0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13dc0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c IG_PAGECACHE]] <
13dd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13de0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a _PAGECACHE</dt>.
13df0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
13e00 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
13e10 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
13e20 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
13e30 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
13e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
13e50 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 ge cache with th
13e60 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 e default page c
13e70 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
13e80 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 ion. .** This c
13e90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f onfiguration sho
13ea0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
13eb0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
13ec0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a n-define page.**
13ed0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
13ee0 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 ation is loaded
13ef0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 using the SQLITE
13f00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 _CONFIG_PCACHE2
13f10 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 option..** There
13f20 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
13f30 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
13f40 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 ion: A pointer t
13f50 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 o 8-byte aligned
13f60 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 .** memory, the
13f70 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 size of each pag
13f80 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 e buffer (sz), a
13f90 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
13fa0 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 pages (N)..** T
13fb0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 he sz argument s
13fc0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a hould be the siz
13fd0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 e of the largest
13fe0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a database page.*
13ff0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 * (a power of tw
14000 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e o between 512 an
14010 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 d 32768) plus a
14020 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 little extra for
14030 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 each.** page he
14040 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 ader. ^The page
14050 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 header size is
14060 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 20 to 40 bytes d
14070 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 epending on.** t
14080 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 he host architec
14090 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 ture. ^It is ha
140a0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 rmless, apart fr
140b0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 om the wasted me
140c0 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 mory,.** to make
140d0 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f sz a little too
140e0 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 large. The fir
140f0 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 st.** argument s
14100 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 hould point to a
14110 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 n allocation of
14120 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
14130 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
14140 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
14150 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
14160 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 ovided by the fi
14170 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
14180 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d satisfy its.** m
14190 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 emory needs for
141a0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 the first N page
141b0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 s that it adds t
141c0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 o cache. ^If ad
141d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
141e0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
141f0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
14200 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
14210 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
14220 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
14230 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
14240 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
14250 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
14260 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 rage space..** T
14270 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 he pointer in th
14280 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
14290 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 must.** be alig
142a0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
142b0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
142c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
142d0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 of SQLite.** wi
142e0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e ll be undefined.
142f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
14310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14320 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a NFIG_HEAP</dt>.*
14330 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
14340 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
14350 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
14360 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
14370 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 will use.** for
14380 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
14390 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 mic memory alloc
143a0 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f ation needs beyo
143b0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 nd those provide
143c0 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c d.** for by [SQL
143d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
143e0 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f CH] and [SQLITE_
143f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
14400 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 ]..** There are
14410 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a three arguments:
14420 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e An 8-byte align
14430 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 ed pointer to th
14440 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 e memory,.** the
14450 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
14460 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 in the memory b
14470 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d uffer, and the m
14480 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
14490 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 n size..** ^If t
144a0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
144b0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
144c0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 nter) is NULL, t
144d0 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 hen SQLite rever
144e0 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 ts.** to using i
144f0 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 ts default memor
14500 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 y allocator (the
14510 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
14520 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 implementation)
14530 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 ,.** undoing any
14540 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f prior invocatio
14550 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e n of [SQLITE_CON
14560 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 FIG_MALLOC]. ^I
14570 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 f the.** memory
14580 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
14590 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b ULL and either [
145a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
145b0 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 MSYS3] or.** [SQ
145c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
145d0 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 YS5] are defined
145e0 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 , then the alter
145f0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a native memory.**
14600 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e allocator is en
14610 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 gaged to handle
14620 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d all of SQLites m
14630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14640 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 needs..** The f
14650 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
14660 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
14670 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 ) must be aligne
14680 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a d to an 8-byte.*
14690 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 * boundary or su
146a0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
146b0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c r of SQLite will
146c0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a be undefined..*
146d0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c * The minimum al
146e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 location size is
146f0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 capped at 2**12
14700 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c . Reasonable val
14710 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d ues.** for the m
14720 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
14730 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 n size are 2**5
14740 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 through 2**8.</d
14750 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14760 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d E_CONFIG_MUTEX]]
14770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14780 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a IG_MUTEX</dt>.**
14790 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
147a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
147b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
147c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
147d0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
147e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
147f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
14800 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
14810 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
14820 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
14830 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 e low-level mute
14840 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 x routines to be
14850 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a used in place.*
14860 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 * the mutex rout
14870 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
14880 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
14890 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
148a0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e of the.** conten
148b0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
148c0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
148d0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 structure befor
148e0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a e the call to.**
148f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
14900 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 ()] returns. ^If
14910 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
14920 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
14930 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
14940 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
14950 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
14960 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
14970 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
14980 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
14990 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
149a0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
149b0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
149c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
149d0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
149e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
149f0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f TEX configuratio
14a00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a n option will.**
14a10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
14a20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a ERROR].</dd>.**.
14a30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14a40 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 IG_GETMUTEX]] <d
14a50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14a60 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a GETMUTEX</dt>.**
14a70 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
14a80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
14a90 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
14aa0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
14ab0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
14ac0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
14ad0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
14ae0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a structure. The.
14af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ** [sqlite3_mute
14b00 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 x_methods].** st
14b10 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
14b20 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
14b30 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 ntly defined mut
14b40 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a ex routines.)^.*
14b50 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
14b60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
14b70 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
14b80 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
14b90 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
14ba0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
14bb0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
14bc0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
14bd0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
14be0 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
14bf0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 for example.
14c00 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
14c10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
14c20 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
14c30 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
14c40 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
14c50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
14c60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
14c70 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
14c80 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
14c90 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
14ca0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
14cb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
14cc0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
14cd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14ce0 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 _GETMUTEX config
14cf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
14d00 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
14d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
14d20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14d30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
14d40 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f DE]] <dt>SQLITE_
14d50 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14d60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
14d70 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
14d80 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 s two arguments
14d90 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 that determine t
14da0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 he default.** me
14db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14dc0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 for the lookasid
14dd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
14de0 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 or on each.** [d
14df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14e00 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 on]. The first
14e10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
14e20 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
14e30 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
14e40 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 slot and the se
14e50 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 cond is the numb
14e60 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 er of.** slots a
14e70 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 llocated to each
14e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
14e90 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 tion.)^ ^(This
14ea0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
14eb0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 ** <i>default</i
14ec0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 > lookaside size
14ed0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 . The [SQLITE_DB
14ee0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14ef0 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 ].** verb to [sq
14f00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
14f10 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 )] can be used t
14f20 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
14f30 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 kaside.** config
14f40 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 uration on indiv
14f50 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e idual connection
14f60 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a s.)^ </dd>.**.**
14f70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14f80 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 _PCACHE2]] <dt>S
14f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14fa0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
14fb0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
14fc0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
14fd0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
14fe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a a pointer to.**
14ff0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
15000 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
15010 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
15020 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 ct specifies the
15030 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f interface.** to
15040 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
15050 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
15060 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ion.)^ ^SQLite
15070 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
15080 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e the.** object an
15090 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 d uses it for pa
150a0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
150b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 allocations.</dd
150c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
150d0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
150e0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
150f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
15100 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
15110 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
15120 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15130 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
15140 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
15150 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
15160 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
15170 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 t. SQLite copie
15180 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 s of the current
15190 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 .** page cache i
151a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
151b0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 to that object.)
151c0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
151d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
151e0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 G]] <dt>SQLITE_C
151f0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a ONFIG_LOG</dt>.*
15200 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 * <dd> The SQLIT
15210 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
15220 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 ion is used to c
15230 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c onfigure the SQL
15240 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 ite.** global [e
15250 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e rror log]..** (^
15260 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
15270 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b G_LOG option tak
15280 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
15290 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 : a pointer to a
152a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 .** function wit
152b0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 h a call signatu
152c0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f re of void(*)(vo
152d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
152e0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 ar*), .** and a
152f0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e pointer to void.
15300 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f ^If the functio
15310 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
15320 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 NULL, it is.**
15330 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 invoked by [sqli
15340 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 te3_log()] to pr
15350 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 ocess each loggi
15360 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
15370 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 he.** function p
15380 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 ointer is NULL,
15390 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 the [sqlite3_log
153a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
153b0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a comes a no-op..*
153c0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e * ^The void poin
153d0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 ter that is the
153e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
153f0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
15400 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 _LOG is.** passe
15410 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
15420 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
15430 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
15440 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 ion-defined logg
15450 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 er.** function w
15460 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e henever that fun
15470 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
15480 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 . ^The second p
15490 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
154a0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
154b0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 on is a copy of
154c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
154d0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 ter to the corre
154e0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c sponding.** [sql
154f0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c ite3_log()] call
15500 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 and is intended
15510 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 to be a [result
15520 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 code] or an.**
15530 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
15540 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 code]. ^The th
15550 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ird parameter pa
15560 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 ssed to the logg
15570 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 er is.** log mes
15580 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 sage after forma
15590 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 tting via [sqlit
155a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a e3_snprintf()]..
155b0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f ** The SQLite lo
155c0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 gging interface
155d0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
155e0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e ; the logger fun
155f0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 ction.** supplie
15600 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
15610 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e tion must not in
15620 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 voke any SQLite
15630 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e interface..** In
15640 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
15650 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 d application, t
15660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
15670 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
15680 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 function must b
15690 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f e threadsafe. </
156a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
156b0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 TE_CONFIG_URI]]
156c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
156d0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 G_URI.** <dd>^(T
156e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
156f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
15700 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 nt of type int.
15710 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 If non-zero, the
15720 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e n.** URI handlin
15730 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
15740 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
15750 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
15760 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
15770 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c ng.** is globall
15780 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 y disabled.)^ ^I
15790 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 f URI handling i
157a0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c s globally enabl
157b0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 ed, all filename
157c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b s.** passed to [
157d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
157e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
157f0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 2()], [sqlite3_o
15800 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 pen16()] or.** s
15810 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
15820 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d of [ATTACH] com
15830 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 mands are interp
15840 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 reted as URIs, r
15850 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 egardless.** of
15860 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
15870 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
15880 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 URI] flag is set
15890 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
158a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
158b0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 is opened. ^If
158c0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 it is globally d
158d0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d isabled, filenam
158e0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 es are.** only i
158f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
15900 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 Is if the SQLITE
15910 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 _OPEN_URI flag i
15920 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a s set when the.*
15930 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
15940 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
15950 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 ^(By default, U
15960 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
15970 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
15980 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
15990 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
159a0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
159b0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
159c0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
159d0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 symbol defined.)
159e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
159f0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
15a00 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 _INDEX_SCAN]] <d
15a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15a20 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
15a30 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 CAN.** <dd>^This
15a40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
15a50 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 single integer a
15a60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
15a70 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a interpreted as.
15a80 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 ** a boolean in
15a90 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 order to enable
15aa0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 or disable the u
15ab0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 se of covering i
15ac0 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 ndices for.** fu
15ad0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 ll table scans i
15ae0 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 n the query opti
15af0 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 mizer. ^The def
15b00 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 ault setting is
15b10 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 determined.** by
15b20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c the [SQLITE_ALL
15b30 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 OW_COVERING_INDE
15b40 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d X_SCAN] compile-
15b50 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 time option, or
15b60 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 is "on".** if th
15b70 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
15b80 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 option is omitte
15b90 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 d..** The abilit
15ba0 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 y to disable the
15bb0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 use of covering
15bc0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c indices for ful
15bd0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a l table scans.**
15be0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 is because some
15bf0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 incorrectly cod
15c00 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 ed legacy applic
15c10 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c ations might mal
15c20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e function.** when
15c30 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f the optimizatio
15c40 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 n is enabled. P
15c50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 roviding the abi
15c60 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 lity to.** disab
15c70 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 le the optimizat
15c80 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f ion allows the o
15c90 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c lder, buggy appl
15ca0 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 ication code to
15cb0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 work.** without
15cc0 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 change even with
15cd0 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
15ce0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
15cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15d00 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 _PCACHE]] [[SQLI
15d10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
15d20 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c CHE]].** <dt>SQL
15d30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
15d40 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e E and SQLITE_CON
15d50 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a FIG_GETPCACHE.**
15d60 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 <dd> These opti
15d70 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 ons are obsolete
15d80 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 and should not
15d90 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 be used by new c
15da0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 ode..** They are
15db0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 retained for ba
15dc0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
15dd0 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f ility but are no
15de0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 w no-ops..** </d
15df0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15e00 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d E_CONFIG_SQLLOG]
15e10 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
15e20 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a CONFIG_SQLLOG.**
15e30 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
15e40 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
15e50 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 le if sqlite is
15e60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
15e70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
15e80 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d BLE_SQLLOG] pre-
15e90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
15ea0 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 defined. The fir
15eb0 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 st argument shou
15ec0 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 ld.** be a point
15ed0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e er to a function
15ee0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 of type void(*)
15ef0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
15f00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
15f10 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
15f20 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 should be of ty
15f30 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 pe (void*). The
15f40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
15f50 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 ked by the libra
15f60 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 ry.** in three s
15f70 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 eparate circumst
15f80 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 ances, identifie
15f90 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 d by the value p
15fa0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 assed as the.**
15fb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
15fc0 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 . If the fourth
15fd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 parameter is 0,
15fe0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
15ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
16000 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
16010 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 cond argument ha
16020 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e s just been open
16030 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 ed. The third ar
16040 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 gument.** points
16050 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e to a buffer con
16060 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 taining the name
16070 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 of the main dat
16080 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 abase file. If t
16090 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
160a0 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 ameter is 1, the
160b0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
160c0 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 ent that the thi
160d0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 rd parameter.**
160e0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 points to has ju
160f0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 st been executed
16100 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 . Or, if the fou
16110 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
16120 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 2, then.** the
16130 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 connection being
16140 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
16150 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
16160 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e is being closed.
16170 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 The.** third pa
16180 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 rameter is passe
16190 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 d NULL In this c
161a0 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ase. An example
161b0 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a of using this.*
161c0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
161d0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 option can be se
161e0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f en in the "test_
161f0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 sqllog.c" source
16200 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 file in.** the
16210 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 canonical SQLite
16220 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 source tree.</d
16230 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
16240 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
16250 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ZE]].** <dt>SQLI
16260 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
16270 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 IZE.** <dd>^SQLI
16280 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
16290 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 IZE takes two 64
162a0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 -bit integer (sq
162b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c lite3_int64) val
162c0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ues.** that are
162d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 the default mmap
162e0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 size limit (the
162f0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
16300 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 for.** [PRAGMA
16310 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 mmap_size]) and
16320 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f the maximum allo
16330 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 wed mmap size li
16340 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 mit..** ^The def
16350 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e ault setting can
16360 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 be overridden b
16370 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 y each database
16380 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
16390 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b .** either the [
163a0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
163b0 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 ] command, or by
163c0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
163d0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
163e0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 _SIZE] file cont
163f0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 rol. ^(The maxi
16400 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 mum allowed mmap
16410 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 size.** cannot
16420 62 65 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 be changed at ru
16430 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 n-time. Nor may
16440 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c the maximum all
16450 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a owed mmap size.*
16460 2a 20 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d * exceed the com
16470 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 pile-time maximu
16480 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 m mmap size set
16490 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
164a0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d E_MAX_MMAP_SIZE]
164b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
164c0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 tion.)^.** ^If e
164d0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 ither argument t
164e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 o this option is
164f0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
16500 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 that argument is
16510 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 .** changed to i
16520 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ts compile-time
16530 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b default..**.** [
16540 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 [SQLITE_CONFIG_W
16550 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a IN32_HEAPSIZE]].
16560 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
16570 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
16580 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 IZE.** <dd>^This
16590 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
165a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c available if SQL
165b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
165c0 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 for Windows.** w
165d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
165e0 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 WIN32_MALLOC] pr
165f0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 e-processor macr
16600 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 o defined..** SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
16620 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 2_HEAPSIZE takes
16630 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e a 32-bit unsign
16640 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 ed integer value
16650 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 .** that specifi
16660 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 es the maximum s
16670 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 ize of the creat
16680 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c ed heap..** </dl
16690 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
166b0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e ETHREAD 1 /* n
166c0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
166d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
166e0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 ITHREAD 2 /*
166f0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
16700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
16710 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a IALIZED 3 /*
16720 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
16730 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
16740 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f LLOC 4 /
16750 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
16760 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
16770 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16780 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 GETMALLOC 5
16790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
167a0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
167b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
167c0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 G_SCRATCH
167d0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 6 /* void*, int
167e0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
167f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16800 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 FIG_PAGECACHE
16810 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 7 /* void*, i
16820 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a nt sz, int N */.
16830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16840 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 ONFIG_HEAP
16850 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 8 /* void*,
16860 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 int nByte, int
16870 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 min */.#define S
16880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
16890 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a STATUS 9 /*
168a0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 boolean */.#def
168b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
168c0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 G_MUTEX 1
168d0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 0 /* sqlite3_mu
168e0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
168f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16900 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 ONFIG_GETMUTEX
16910 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 11 /* sqlite
16920 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
16930 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c */./* previousl
16940 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f y SQLITE_CONFIG_
16950 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 CHUNKALLOC 12 wh
16960 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 ich is now unuse
16970 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 d. */ .#define S
16980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
16990 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a KASIDE 13 /*
169a0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
169b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
169c0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 G_PCACHE 1
169d0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 4 /* no-op */.#
169e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
169f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 NFIG_GETPCACHE
16a00 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 15 /* no-op *
16a10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16a20 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 _CONFIG_LOG
16a30 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 16 /* xFun
16a40 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 c, void* */.#def
16a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16a60 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 G_URI 1
16a70 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 7 /* int */.#de
16a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16a90 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 IG_PCACHE2
16aa0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 18 /* sqlite3_p
16ab0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 cache_methods2*
16ac0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16ad0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
16ae0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c HE2 19 /* sql
16af0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
16b00 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 ods2* */.#define
16b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
16b20 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
16b30 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f AN 20 /* int */
16b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16b50 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 CONFIG_SQLLOG
16b60 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 21 /* xSqll
16b70 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 og, void* */.#de
16b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16b90 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 IG_MMAP_SIZE
16ba0 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 22 /* sqlite3_i
16bb0 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e nt64, sqlite3_in
16bc0 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t64 */.#define S
16bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
16be0 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 32_HEAPSIZE
16bf0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 23 /* int nByt
16c00 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e */../*.** CAPI
16c10 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
16c20 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 onnection Config
16c30 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
16c40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
16c50 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
16c60 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
16c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16c80 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
16c90 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
16ca0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16cb0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
16cc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
16cd0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
16ce0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
16cf0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
16d00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
16d10 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
16d20 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
16d30 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
16d40 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
16d50 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
16d60 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
16d70 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
16d80 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
16d90 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
16da0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
16db0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
16dc0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
16dd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
16de0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
16df0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
16e00 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
16e10 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
16e20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
16e30 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
16e40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
16e50 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
16e60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
16e70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
16e80 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
16e90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
16ea0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
16eb0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
16ec0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
16ed0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
16ee0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16ef0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
16f00 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
16f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
16f20 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
16f30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
16f40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
16f50 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
16f60 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
16f70 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
16f80 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 a memory buffer
16f90 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
16fa0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
16fb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
16fc0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 ent after the SQ
16fd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
16fe0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 OKASIDE verb.**
16ff0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 may be NULL in w
17000 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
17010 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
17020 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 he.** lookaside
17030 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 buffer itself us
17040 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
17050 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 loc()]. ^The sec
17060 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
17070 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
17080 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
17090 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 ffer slot. ^The
170a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
170b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
170c0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 .** slots. The
170d0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
170e0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
170f0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
17100 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a greater than.**
17110 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 or equal to the
17120 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 product of the
17130 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 second and third
17140 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 arguments. The
17150 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 buffer.** must
17160 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
17170 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
17180 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e . ^If the secon
17190 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
171a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
171b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f _LOOKASIDE is no
171c0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 t a multiple of
171d0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 8, it is interna
171e0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 lly.** rounded d
171f0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 own to the next
17200 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 smaller multiple
17210 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f of 8. ^(The lo
17220 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a okaside memory.*
17230 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
17240 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
17250 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e onnection can on
17260 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 ly be changed wh
17270 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 en that.** conne
17280 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 ction is not cur
17290 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f rently using loo
172a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f kaside memory, o
172b0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 r in other words
172c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 .** when the "cu
172d0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 rrent value" ret
172e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
172f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 ite3_db_status](
17300 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 D,[SQLITE_CONFIG
17310 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 _LOOKASIDE],...)
17320 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 is zero..** Any
17330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e attempt to chan
17340 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
17350 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 memory configur
17360 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 ation when looka
17370 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 side.** memory i
17380 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 s in use leaves
17390 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
173a0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 n unchanged and
173b0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c returns .** [SQL
173c0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 ITE_BUSY].)^</dd
173d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
173e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
173f0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 LE_FKEY</dt>.**
17400 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
17410 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
17420 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
17430 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f he enforcement o
17440 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 f.** [foreign ke
17450 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 y constraints].
17460 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
17470 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
17480 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
17490 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
174a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
174b0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
174c0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
174d0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ent,.** positive
174e0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e to enable FK en
174f0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 forcement or neg
17500 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 ative to leave F
17510 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a K enforcement.**
17520 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 unchanged. The
17530 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
17540 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
17550 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
17560 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
17570 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
17580 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
17590 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
175a0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 is off or on.**
175b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
175c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
175d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
175e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
175f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
17600 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 se the FK enforc
17610 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 ement setting is
17620 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 not reported ba
17630 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ck. </dd>.**.**
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
17650 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
17660 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ER</dt>.** <dd>
17670 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
17680 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
17690 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 r disable [CREAT
176a0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
176b0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 gers]..** There
176c0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
176d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
176e0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
176f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
17700 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
17710 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 0 to disable tr
17720 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 iggers,.** posit
17730 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 ive to enable tr
17740 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 iggers or negati
17750 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
17760 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
17770 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 d..** The second
17780 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
17790 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
177a0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
177b0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
177c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
177d0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 e whether trigge
177e0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 rs are disabled
177f0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f or enabled.** fo
17800 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
17810 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
17820 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
17830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
17840 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
17850 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 the trigger set
17860 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
17870 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
17880 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a .**.** </dl>.*/.
17890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
178a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
178b0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a E 1001 /*
178c0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
178d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
178e0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
178f0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 _FKEY 1002
17900 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
17910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
17920 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
17930 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 IGGER 1003 /*
17940 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a int int* */.../*
17950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
17960 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
17970 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
17980 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Codes.**.** ^The
17990 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
179a0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
179b0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
179c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
179d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
179e0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 sult codes] feat
179f0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e ure of SQLite. ^
17a00 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
17a10 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 ult.** codes are
17a20 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
17a30 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 ault for histori
17a40 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 cal compatibilit
17a50 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 y..*/.SQLITE_API
17a60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
17a70 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
17a80 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
17a90 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
17aa0 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
17ab0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a nsert Rowid.**.*
17ac0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e * ^Each entry in
17ad0 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 most SQLite tab
17ae0 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 les (except for
17af0 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 [WITHOUT ROWID]
17b00 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 tables).** has a
17b10 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 unique 64-bit s
17b20 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 igned.** integer
17b30 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 key called the
17b40 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 [ROWID | "rowid"
17b50 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 ]. ^The rowid is
17b60 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c always availabl
17b70 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 e.** as an undec
17b80 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d lared column nam
17b90 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f ed ROWID, OID, o
17ba0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e r _ROWID_ as lon
17bb0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 g as those.** na
17bc0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f mes are not also
17bd0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 used by explici
17be0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
17bf0 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 umns. ^If.** the
17c00 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
17c10 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 umn of type [INT
17c20 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
17c30 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 ] then that colu
17c40 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 mn.** is another
17c50 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 alias for the r
17c60 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 owid..**.** ^The
17c70 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
17c80 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e sert_rowid(D) in
17c90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
17ca0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
17cb0 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 he .** most rece
17cc0 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 nt successful [I
17cd0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f NSERT] into a ro
17ce0 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 wid table or [vi
17cf0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 rtual table].**
17d00 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e on database conn
17d10 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e ection D..** ^In
17d20 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 serts into [WITH
17d30 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
17d40 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 s are not record
17d50 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 ed..** ^If no su
17d60 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
17d70 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 ]s into rowid ta
17d80 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 bles.** have eve
17d90 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
17da0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17db0 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 ction D, .** the
17dc0 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 n sqlite3_last_i
17dd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 nsert_rowid(D) r
17de0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
17df0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 ** ^(If an [INSE
17e00 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 RT] occurs withi
17e10 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 n a trigger or w
17e20 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c ithin a [virtual
17e30 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f table].** metho
17e40 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 d, then this rou
17e50 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e tine will return
17e60 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
17e70 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
17e80 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 row as long as t
17e90 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
17ea0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
17eb0 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a od is running..*
17ec0 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 * But once the t
17ed0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
17ee0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 l table method e
17ef0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 nds, the value r
17f00 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 eturned .** by t
17f10 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 his routine reve
17f20 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 rts to what it w
17f30 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 as before the tr
17f40 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
17f50 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 .** table method
17f60 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 began.)^.**.**
17f70 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
17f80 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
17f90 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
17fa0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
17fb0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
17fc0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
17fd0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
17fe0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
17ff0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
18000 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
18010 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
18020 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
18030 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
18040 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
18050 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
18060 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
18070 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
18080 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
18090 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
180a0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
180b0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
180c0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
180d0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
180e0 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
180f0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
18100 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
18110 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
18120 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
18130 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
18140 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
18150 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
18160 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
18170 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
18180 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
18190 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
181a0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
181b0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
181c0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
181d0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
181e0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
181f0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
18200 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
18210 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
18220 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
18230 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
18240 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
18250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
18260 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
18270 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
18280 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
18290 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
182a0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
182b0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
182c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
182d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
182e0 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
182f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
18300 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
18310 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
18320 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
18330 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
18340 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
18350 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
18360 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
18370 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18380 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
18390 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
183a0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
183b0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
183c0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
183d0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
183e0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
183f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
18400 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
18410 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
18420 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
18430 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
18440 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
18450 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
18460 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
18470 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
18480 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
18490 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
184a0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
184b0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
184c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
184d0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
184e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
184f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
18500 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
18510 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
18520 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 parameter..** ^(
18530 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
18540 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
18550 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
18560 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
18570 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
18580 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
18590 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
185a0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
185b0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
185c0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b rs or [foreign k
185d0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
185e0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 not counted.)^ U
185f0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 se the.** [sqlit
18600 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
18610 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ()] function to
18620 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
18630 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
18640 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 .** including ch
18650 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
18660 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 triggers and for
18670 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
18680 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 ..**.** ^Changes
18690 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
186a0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 are simulated by
186b0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
186c0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 trigger].** are
186d0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e not counted. On
186e0 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 ly real table ch
186f0 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
18700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f d..**.** ^(A "ro
18710 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
18720 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
18730 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
18740 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
18750 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
18760 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
18770 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
18780 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
18790 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
187a0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 ffects of [REPLA
187b0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
187c0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
187d0 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
187e0 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 ocessing, [DROP
187f0 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e TABLE], or by an
18800 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 y other.** mecha
18810 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 nisms do not cou
18820 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 nt as direct row
18830 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a changes.)^.**.*
18840 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
18850 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
18860 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
18870 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
18880 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
18890 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 cript of a [CREA
188a0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
188b0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 gger]. .** Most
188c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
188d0 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
188e0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
188f0 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
18900 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
18910 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
18920 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
18930 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
18940 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
18950 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
18960 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
18970 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
18980 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
18990 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
189a0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
189b0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
189c0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
189d0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 .** ^Calling [sq
189e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
189f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
18a00 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
18a10 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
18a20 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
18a30 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ontext..**.** ^T
18a40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
18a50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
18a60 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 of direct row ch
18a70 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 anges in the.**
18a80 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
18a90 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
18aa0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
18ab0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a within the same.
18ac0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
18ad0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c xt..**.** ^Thus,
18ae0 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
18af0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
18b00 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
18b10 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
18b20 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
18b30 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
18b40 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
18b50 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
18b60 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
18b70 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
18b80 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 vel. ^(Within t
18b90 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 he body of a tri
18ba0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c gger,.** the sql
18bb0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 ite3_changes() i
18bc0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
18bd0 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 called to find t
18be0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
18bf0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
18c00 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
18c10 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
18c20 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
18c30 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 .** statement wi
18c40 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
18c50 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
18c60 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 r..** However, t
18c70 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e he number return
18c80 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
18c90 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 ude changes.** c
18ca0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 aused by subtrig
18cb0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 gers since those
18cc0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 have their own
18cd0 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a context.)^.**.**
18ce0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
18cf0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
18d00 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
18d10 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
18d20 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
18d30 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
18d40 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
18d50 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
18d60 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
18d70 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
18d80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
18d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
18da0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
18db0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
18dc0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
18dd0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
18de0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
18df0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
18e00 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
18e10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
18e20 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
18e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18e40 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
18e50 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
18e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
18e70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
18e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 e number of row
18e90 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
18ea0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b y [INSERT],.** [
18eb0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 UPDATE] or [DELE
18ec0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 TE] statements s
18ed0 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 ince the [databa
18ee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
18ef0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 as opened..** ^(
18f00 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e The count return
18f10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f ed by sqlite3_to
18f20 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e tal_changes() in
18f30 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 cludes all chang
18f40 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b es.** from all [
18f50 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
18f60 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 trigger] contex
18f70 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d ts and changes m
18f80 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 ade by.** [forei
18f90 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e gn key actions].
18fa0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
18fb0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
18fc0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
18fd0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
18fe0 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 t [REPLACE] cons
18ff0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 traints,.** do r
19000 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 ollbacks or ABOR
19010 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 T processing, or
19020 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 [DROP TABLE] pr
19030 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a ocessing. The.*
19040 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 * count does not
19050 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 include rows of
19060 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 views that fire
19070 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
19080 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f trigger],.** tho
19090 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 ugh if the INSTE
190a0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 AD OF trigger ma
190b0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 kes changes of i
190c0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 ts own, those ch
190d0 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f anges .** are co
190e0 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 unted.)^.** ^The
190f0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
19100 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f hanges() functio
19110 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 n counts the cha
19120 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a nges as soon as.
19130 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
19140 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
19150 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 is completed (w
19160 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
19170 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 t handle.** is p
19180 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
19190 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
191a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
191b0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 )])..**.** See a
191c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
191d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
191e0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
191f0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
19200 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 gma], and the [t
19210 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 otal_changes() S
19220 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
19230 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
19240 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
19250 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
19260 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
19270 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
19280 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
19290 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
192a0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
192b0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
192c0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
192d0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
192e0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
192f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
19300 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
19310 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
19320 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
19330 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
19340 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 g Query.**.** ^T
19350 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
19360 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
19370 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
19380 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
19390 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
193a0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
193b0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
193c0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
193d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
193e0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
193f0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
19400 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
19410 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
19420 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
19430 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
19440 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
19450 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
19460 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
19470 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
19480 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
19490 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
194a0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
194b0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
194c0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
194d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
194e0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
194f0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
19500 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
19510 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
19520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
19530 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
19540 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
19550 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
19560 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
19570 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
19580 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
19590 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
195a0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
195b0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
195c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
195d0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
195e0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
195f0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
19600 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
19610 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
19620 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
19630 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
19640 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
19650 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
19660 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
19670 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
19680 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
19690 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
196a0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
196b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
196c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
196d0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
196e0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
196f0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
19700 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
19710 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
19720 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
19730 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
19740 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
19750 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
19760 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
19770 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
19780 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
19790 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
197a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
197b0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
197c0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
197d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
197e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
197f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
19800 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
19810 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
19820 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
19830 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
19840 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
19850 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
19860 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
19870 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
19880 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
19890 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
198a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
198b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
198c0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
198d0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
198e0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
198f0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
19900 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
19910 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
19920 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
19930 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
19940 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
19950 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
19960 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
19970 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
19980 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
19990 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
199a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
199b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
199c0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
199d0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
199e0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
199f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
19a00 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
19a10 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
19a20 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
19a30 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
19a40 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
19a50 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 ely happen..*/.S
19a60 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
19a70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19a80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
19a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
19aa0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
19ab0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
19ac0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
19ad0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
19ae0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
19af0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
19b00 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
19b10 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
19b20 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
19b30 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
19b40 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
19b50 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
19b60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
19b70 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
19b80 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
19b90 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
19ba0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
19bb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
19bc0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
19bd0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
19be0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
19bf0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
19c00 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
19c10 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
19c20 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
19c30 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
19c40 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
19c50 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
19c60 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
19c70 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
19c80 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
19c90 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
19ca0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
19cb0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
19cc0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
19cd0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
19ce0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
19cf0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
19d00 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
19d10 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
19d20 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
19d30 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
19d40 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
19d50 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
19d60 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
19d70 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
19d80 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
19d90 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
19da0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
19db0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
19dc0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
19dd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
19de0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
19df0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
19e00 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
19e10 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
19e20 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
19e30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
19e40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
19e50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
19e60 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
19e70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
19e80 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
19e90 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
19ea0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
19eb0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
19ec0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
19ed0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
19ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
19ef0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
19f00 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
19f10 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
19f20 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
19f30 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
19f40 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
19f50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
19f60 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
19f70 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
19f80 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
19f90 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
19fa0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
19fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
19fc0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
19fd0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
19fe0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
19ff0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
1a000 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
1a010 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
1a020 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
1a030 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
1a040 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
1a050 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
1a060 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
1a070 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1a080 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1a090 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1a0a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1a0b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
1a0c0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
1a0d0 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 der..*/.SQLITE_A
1a0e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1a0f0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
1a100 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 ar *sql);.SQLITE
1a110 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1a120 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
1a130 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
1a140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1a150 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
1a160 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
1a170 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
1a180 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1a190 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
1a1a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
1a1b0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
1a1c0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
1a1d0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
1a1e0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
1a1f0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
1a200 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
1a210 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
1a220 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
1a230 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
1a240 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
1a250 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
1a260 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1a270 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
1a280 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
1a290 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
1a2a0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
1a2b0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
1a2c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
1a2d0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
1a2e0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
1a2f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
1a300 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
1a310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1a320 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1a330 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1a340 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
1a350 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
1a360 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
1a370 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
1a380 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1a390 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
1a3a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
1a3b0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
1a3c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
1a3d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
1a3e0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
1a3f0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
1a400 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
1a410 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
1a420 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
1a430 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
1a440 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
1a450 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
1a460 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
1a470 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
1a480 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
1a490 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
1a4a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
1a4b0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
1a4c0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
1a4d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1a4e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
1a4f0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
1a500 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
1a510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
1a520 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
1a530 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
1a540 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
1a550 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
1a560 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
1a570 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
1a580 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
1a590 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
1a5a0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
1a5b0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
1a5c0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
1a5d0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
1a5e0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
1a5f0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
1a600 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
1a610 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
1a620 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
1a630 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
1a640 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
1a650 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
1a660 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
1a670 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
1a680 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
1a690 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
1a6a0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
1a6b0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
1a6c0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
1a6d0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
1a6e0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
1a6f0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
1a700 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
1a710 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
1a720 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
1a730 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
1a740 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
1a750 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
1a760 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
1a770 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
1a780 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1a790 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
1a7a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1a7b0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
1a7c0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
1a7d0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
1a7e0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
1a7f0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
1a800 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
1a810 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
1a820 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
1a830 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
1a840 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
1a850 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
1a860 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
1a870 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
1a880 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
1a890 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
1a8a0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
1a8b0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
1a8c0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
1a8d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1a8e0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
1a8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
1a900 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
1a910 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
1a920 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
1a930 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
1a940 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
1a950 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
1a960 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
1a970 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
1a980 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
1a990 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
1a9a0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
1a9b0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
1a9c0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
1a9d0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
1a9e0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
1a9f0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
1aa00 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
1aa10 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
1aa20 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
1aa30 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
1aa40 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
1aa50 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
1aa60 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
1aa70 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
1aa80 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
1aa90 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
1aaa0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
1aab0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
1aac0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
1aad0 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
1aae0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
1aaf0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
1ab00 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
1ab10 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
1ab20 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
1ab30 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
1ab40 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
1ab50 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
1ab60 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
1ab70 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
1ab80 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
1ab90 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
1aba0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
1abb0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
1abc0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
1abd0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
1abe0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
1abf0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
1ac00 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
1ac10 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
1ac20 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
1ac30 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
1ac40 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
1ac50 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
1ac60 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
1ac70 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
1ac80 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
1ac90 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
1aca0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
1acb0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
1acc0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1acd0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
1ace0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
1acf0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
1ad00 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
1ad10 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
1ad20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
1ad30 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1ad40 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
1ad50 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
1ad60 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
1ad70 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
1ad80 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
1ad90 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
1ada0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
1adb0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
1adc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1add0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1ade0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1adf0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
1ae00 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
1ae10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
1ae20 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
1ae30 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
1ae40 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
1ae50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ae60 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
1ae70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
1ae80 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
1ae90 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 sy handler..*/.S
1aea0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1aeb0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1aec0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
1aed0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
1aee0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1aef0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
1af00 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
1af10 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
1af20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
1af30 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
1af40 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
1af50 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
1af60 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
1af70 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
1af80 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
1af90 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
1afa0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
1afb0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
1afc0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
1afd0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1afe0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
1aff0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
1b000 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
1b010 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1b020 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
1b030 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
1b040 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
1b050 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
1b060 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
1b070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
1b080 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
1b090 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
1b0a0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
1b0b0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
1b0c0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
1b0d0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
1b0e0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
1b0f0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
1b100 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
1b110 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
1b120 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
1b130 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
1b140 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1b150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
1b160 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
1b170 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
1b180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
1b190 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
1b1a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
1b1b0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
1b1c0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
1b1d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
1b1e0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
1b1f0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
1b200 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 red.)^.*/.SQLITE
1b210 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1b220 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
1b230 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
1b240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1b250 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
1b260 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
1b270 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a ng Queries.**.**
1b280 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 This is a legac
1b290 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 y interface that
1b2a0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f is preserved fo
1b2b0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
1b2c0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 atibility..** Us
1b2d0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
1b2e0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d ace is not recom
1b2f0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 mended..**.** De
1b300 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 finition: A <b>r
1b310 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 esult table</b>
1b320 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 is memory data s
1b330 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 tructure created
1b340 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 by the.** [sqli
1b350 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
1b360 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 interface. A r
1b370 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f esult table reco
1b380 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c rds the.** compl
1b390 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 ete query result
1b3a0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f s from one or mo
1b3b0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a re queries..**.*
1b3c0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 * The table conc
1b3d0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e eptually has a n
1b3e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e umber of rows an
1b3f0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a d columns. But.
1b400 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 ** these numbers
1b410 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 are not part of
1b420 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1b430 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 e itself. These
1b440 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 .** numbers are
1b450 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 obtained separat
1b460 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 ely. Let N be t
1b470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
1b480 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 s.** and M be th
1b490 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1b4a0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 mns..**.** A res
1b4b0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 ult table is an
1b4c0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
1b4d0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e s to zero-termin
1b4e0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
1b4f0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 gs..** There are
1b500 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 (N+1)*M element
1b510 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 s in the array.
1b520 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 The first M poi
1b530 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 nters point.** t
1b540 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1b550 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 d strings that
1b560 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 contain the name
1b570 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
1b580 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 ..** The remaini
1b590 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 ng entries all p
1b5a0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 oint to query re
1b5b0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c sults. NULL val
1b5c0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e ues result.** in
1b5d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 NULL pointers.
1b5e0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 All other value
1b5f0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 s are in their U
1b600 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
1b610 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 ated.** string r
1b620 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 epresentation as
1b630 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1b640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
1b650 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 t()]..**.** A re
1b660 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 sult table might
1b670 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 consist of one
1b680 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 or more memory a
1b690 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 llocations..** I
1b6a0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
1b6b0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 pass a result t
1b6c0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f able directly to
1b6d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1b6e0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 ]..** A result t
1b6f0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 able should be d
1b700 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 eallocated using
1b710 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1b720 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e able()]..**.** ^
1b730 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f (As an example o
1b740 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
1b750 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f le format, suppo
1b760 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c se a query resul
1b770 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f t.** is as follo
1b780 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1b790 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1b7a0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 Name
1b7b0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 | Age.**
1b7c0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d --------------
1b7d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 ---------.**
1b7e0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 Alice
1b7f0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 | 43.** B
1b800 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a ob | 28.
1b810 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 ** Cindy
1b820 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f | 21.** </
1b830 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1b840 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 >.**.** There ar
1b850 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d e two column (M=
1b860 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f =2) and three ro
1b870 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 ws (N==3). Thus
1b880 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 the.** result t
1b890 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 able has 8 entri
1b8a0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 es. Suppose the
1b8b0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
1b8c0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e stored.** in an
1b8d0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 array names azR
1b8e0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 esult. Then azR
1b8f0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 esult holds this
1b900 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 content:.**.**
1b910 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1b920 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 >.** azRe
1b930 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e sult[0] = "N
1b940 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ame";.**
1b950 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 azResult[1]
1b960 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 = "Age";.**
1b970 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1b980 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 2] = "Alice";.**
1b990 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b9a0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a [3] = "43";.
1b9b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b9c0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 lt[4] = "Bob
1b9d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b9e0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 esult[5] = "
1b9f0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 28";.** a
1ba00 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d zResult[6] =
1ba10 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 "Cindy";.**
1ba20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1ba30 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c ;7] = "21";.** <
1ba40 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1ba50 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1ba60 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1ba70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
1ba80 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
1ba90 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
1baa0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
1bab0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
1bac0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1bad0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
1bae0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
1baf0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eter and returns
1bb00 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
1bb10 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 to the.** pointe
1bb20 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 r given in its 3
1bb30 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a rd parameter..**
1bb40 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 .** After the ap
1bb50 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 plication has fi
1bb60 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 nished with the
1bb70 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 result from sqli
1bb80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
1bb90 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 .** it must pass
1bba0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1bbb0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c e pointer to sql
1bbc0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1bbd0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a ) in order to.**
1bbe0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1bbf0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c ory that was mal
1bc00 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 loced. Because
1bc10 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a of the way the.*
1bc20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
1bc30 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 c()] happens wit
1bc40 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hin sqlite3_get_
1bc50 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c table(), the cal
1bc60 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ling.** function
1bc70 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f must not try to
1bc80 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 call [sqlite3_f
1bc90 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e ree()] directly.
1bca0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 Only.** [sqlit
1bcb0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1bcc0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 is able to rele
1bcd0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 ase the memory p
1bce0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 roperly and safe
1bcf0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ly..**.** The sq
1bd00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1bd10 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
1bd20 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 mplemented as a
1bd30 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a wrapper around.*
1bd40 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * [sqlite3_exec(
1bd50 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 )]. The sqlite3
1bd60 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 _get_table() rou
1bd70 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 tine does not ha
1bd80 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ve access.** to
1bd90 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 any internal dat
1bda0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 a structures of
1bdb0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 SQLite. It uses
1bdc0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 only the public
1bdd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 .** interface de
1bde0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 fined here. As
1bdf0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 a consequence, e
1be00 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 rrors that occur
1be10 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 in the.** wrapp
1be20 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 er layer outside
1be30 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c of the internal
1be40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1be50 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a ] call are not.*
1be60 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 * reflected in s
1be70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
1be80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
1be90 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 ode()] or.** [sq
1bea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
1beb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1bec0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
1bed0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
1bee0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
1bef0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
1bf00 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1bf10 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
1bf20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
1bf30 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
1bf40 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
1bf50 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
1bf60 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
1bf70 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
1bf80 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1bf90 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
1bfa0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
1bfb0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
1bfc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1bfd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
1bfe0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1bff0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
1c000 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
1c010 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
1c020 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
1c030 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 I void sqlite3_f
1c040 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1c050 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1c060 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1c070 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1c080 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1c090 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1c0a0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1c0b0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1c0c0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1c0d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1c0e0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1c0f0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 library..**.**
1c100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 ^The sqlite3_mpr
1c110 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
1c120 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
1c130 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
1c140 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
1c150 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
1c160 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
1c170 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
1c180 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1c190 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
1c1a0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
1c1b0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
1c1c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
1c1d0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
1c1e0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
1c1f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1c200 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1c210 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
1c220 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
1c230 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
1c240 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
1c250 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
1c260 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 (The sqlite3_snp
1c270 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1c280 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
1c290 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
1c2a0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
1c2b0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
1c2c0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
1c2d0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
1c2e0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
1c2f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1c300 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
1c310 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
1c320 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1c330 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
1c340 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
1c350 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
1c360 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
1c370 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
1c380 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 f().)^ This is
1c390 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
1c3a0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
1c3b0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
1c3c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
1c3d0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
1c3e0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e patibility. ^(N
1c3f0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 ote also that sq
1c400 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1c410 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f .** returns a po
1c420 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 inter to its buf
1c430 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 fer instead of t
1c440 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1c450 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 characters actua
1c460 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
1c470 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 the buffer.)^
1c480 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
1c490 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1c4a0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
1c4b0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
1c4c0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
1c4d0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
1c4e0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
1c4f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1c500 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1c510 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
1c520 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
1c530 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1c540 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 .** ^As long as
1c550 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
1c560 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
1c570 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
1c580 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
1c590 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
1c5a0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
1c5b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1c5c0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a . ^The first.**
1c5d0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 parameter "n" i
1c5e0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 s the total size
1c5f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 of the buffer,
1c600 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 including space
1c610 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 for.** the zero
1c620 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 terminator. So
1c630 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 the longest stri
1c640 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 ng that can be c
1c650 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 ompletely.** wri
1c660 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 tten will be n-1
1c670 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
1c680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1c690 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 vsnprintf() rout
1c6a0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 ine is a varargs
1c6b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 version of sqli
1c6c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a te3_snprintf()..
1c6d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1c6e0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
1c6f0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
1c700 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
1c710 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
1c720 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
1c730 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
1c740 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
1c750 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
1c760 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
1c770 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
1c780 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
1c790 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
1c7a0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
1c7b0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1c7c0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1c7d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1c7e0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1c7f0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
1c800 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1c810 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
1c820 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
1c830 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
1c840 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
1c850 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
1c860 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
1c870 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
1c880 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
1c890 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
1c8a0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
1c8b0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
1c8c0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
1c8d0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
1c8e0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
1c8f0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
1c900 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
1c910 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
1c920 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
1c930 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
1c940 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1c950 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1c960 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
1c970 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
1c980 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
1c990 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1c9a0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
1c9b0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
1c9c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1c9d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1c9e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c9f0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1ca00 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1ca10 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1ca20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
1ca30 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
1ca40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1ca50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1ca60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1ca70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1ca80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1ca90 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
1caa0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
1cab0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
1cac0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
1cad0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
1cae0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
1caf0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
1cb00 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1cb10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1cb20 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1cb30 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1cb40 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
1cb50 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
1cb60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1cb70 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
1cb80 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
1cb90 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
1cba0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
1cbb0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
1cbc0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
1cbd0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
1cbe0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1cbf0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
1cc00 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
1cc10 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
1cc20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1cc30 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1cc40 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
1cc50 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
1cc60 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
1cc70 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
1cc80 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
1cc90 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
1cca0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
1ccb0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
1ccc0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
1ccd0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
1cce0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
1ccf0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
1cd00 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
1cd10 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
1cd20 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
1cd30 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
1cd40 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
1cd50 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
1cd60 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
1cd70 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
1cd80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1cd90 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
1cda0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
1cdb0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
1cdc0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
1cdd0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
1cde0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
1cdf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1ce00 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1ce10 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1ce20 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1ce30 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1ce40 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
1ce50 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1ce60 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1ce70 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1ce80 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1ce90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1cea0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
1ceb0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
1cec0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
1ced0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
1cee0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
1cef0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
1cf00 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
1cf10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1cf20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1cf30 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
1cf40 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1cf50 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 "%s" but with th
1cf60 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
1cf70 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
1cf80 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
1cf90 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
1cfa0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
1cfb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1cfc0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
1cfd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
1cfe0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
1cff0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d char *sqlite3_m
1d000 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1d010 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f r*,...);.SQLITE_
1d020 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
1d030 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
1d040 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1d050 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1d060 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
1d070 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1d080 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
1d090 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1d0a0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 *sqlite3_vsnpri
1d0b0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1d0c0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1d0d0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 st);../*.** CAPI
1d0e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1d0f0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
1d100 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
1d110 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
1d120 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
1d130 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
1d140 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
1d150 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1d160 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
1d170 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
1d180 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
1d190 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
1d1a0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
1d1b0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
1d1c0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
1d1d0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
1d1e0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
1d1f0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1d200 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
1d210 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
1d220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1d230 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1d240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1d250 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
1d260 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
1d270 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
1d280 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
1d290 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
1d2a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1d2b0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
1d2c0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
1d2d0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
1d2e0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
1d2f0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
1d300 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
1d310 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
1d320 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
1d330 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
1d340 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1d350 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
1d360 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
1d370 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
1d380 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
1d390 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
1d3a0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
1d3b0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
1d3c0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1d3d0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
1d3e0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
1d3f0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
1d400 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
1d410 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
1d420 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
1d430 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
1d440 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
1d450 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
1d460 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
1d470 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
1d480 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
1d490 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
1d4a0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
1d4b0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
1d4c0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
1d4d0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
1d4e0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
1d4f0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
1d500 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
1d510 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1d520 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
1d530 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
1d540 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
1d550 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1d560 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
1d570 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
1d580 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
1d590 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1d5a0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1d5b0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
1d5c0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
1d5d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
1d5e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1d5f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
1d600 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 oc()..**.** ^(Th
1d610 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
1d620 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
1d630 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
1d640 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
1d650 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
1d660 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
1d670 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
1d680 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
1d690 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
1d6a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d6b0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
1d6c0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
1d6d0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 arameter.)^ ^ If
1d6e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1d6f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1d700 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
1d710 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1d720 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
1d730 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
1d740 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1d750 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
1d760 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1d770 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1d780 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1d790 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 ()..** ^If the s
1d7a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1d7b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1d7c0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a oc() is zero or.
1d7d0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
1d7e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1d7f0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
1d800 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
1d810 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 sqlite3_free(P)
1d820 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 where P is the f
1d830 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1d840 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1d850 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 c()..** ^sqlite3
1d860 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
1d870 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1d880 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
1d890 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
1d8a0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
1d8b0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
1d8c0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
1d8d0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
1d8e0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 ** ^If M is the
1d8f0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
1d900 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
1d910 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
1d920 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
1d930 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
1d940 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
1d950 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
1d960 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
1d970 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
1d980 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
1d990 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
1d9a0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
1d9b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d9c0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
1d9d0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
1d9e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
1d9f0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
1da00 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
1da10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1da20 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
1da30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
1da40 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1da50 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1da60 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1da70 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1da80 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1da90 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1daa0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1dab0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1dac0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1dad0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1dae0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1daf0 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1db00 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1db10 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1db20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1db30 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1db40 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1db50 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1db60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1db70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1db80 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1db90 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1dba0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1dbb0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1dbc0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1dbd0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1dbe0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1dbf0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1dc00 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1dc10 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1dc20 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1dc30 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1dc40 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1dc50 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1dc60 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1dc70 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1dc80 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1dc90 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1dca0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1dcb0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1dcc0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1dcd0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1dce0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1dcf0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1dd00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1dd10 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1dd20 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1dd30 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1dd40 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1dd50 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1dd60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1dd70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1dd80 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1dd90 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1dda0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1ddb0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1ddc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1ddd0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1dde0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1ddf0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1de00 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1de10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1de20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1de30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1de40 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1de50 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1de60 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1de70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1de80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1de90 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1dea0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1deb0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1dec0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1ded0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1dee0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1def0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1df00 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c alloc()]..*/.SQL
1df10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
1df20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
1df30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
1df40 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
1df50 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
1df60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1df70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
1df80 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1df90 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
1dfa0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
1dfb0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 cs.**.** SQLite
1dfc0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
1dfd0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
1dfe0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
1dff0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
1e000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
1e010 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
1e020 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
1e030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1e040 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
1e050 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
1e060 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
1e070 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
1e080 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b em..**.** ^The [
1e090 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1e0a0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 sed()] routine r
1e0b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
1e0c0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 r of bytes.** of
1e0d0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c memory currentl
1e0e0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d y outstanding (m
1e0f0 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 alloced but not
1e100 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 freed)..** ^The
1e110 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1e120 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 highwater()] rou
1e130 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
1e140 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 maximum.** valu
1e150 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 e of [sqlite3_me
1e160 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e mory_used()] sin
1e170 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 ce the high-wate
1e180 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 r mark.** was la
1e190 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 st reset. ^The
1e1a0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
1e1b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
1e1c0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a ry_used()] and.*
1e1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1e1e0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
1e1f0 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 nclude any overh
1e200 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 ead.** added by
1e210 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d SQLite in its im
1e220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1e230 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1e240 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f )],.** but not o
1e250 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 verhead added by
1e260 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 the any underly
1e270 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 ing system libra
1e280 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 ry.** routines t
1e290 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c hat [sqlite3_mal
1e2a0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e loc()] may call.
1e2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
1e2c0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 ry high-water ma
1e2d0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 rk is reset to t
1e2e0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
1e2f0 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f of.** [sqlite3_
1e300 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 memory_used()] i
1e310 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
1e320 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a e parameter to.*
1e330 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1e340 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
1e350 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 s true. ^The va
1e360 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
1e370 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
1e380 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d ry_highwater(1)]
1e390 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 is the high-wat
1e3a0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 er mark.** prior
1e3b0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a to the reset..*
1e3c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
1e3d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1e3e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
1e3f0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1e400 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
1e410 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1e420 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
1e430 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
1e440 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
1e450 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
1e460 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 nerator.**.** SQ
1e470 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
1e480 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
1e490 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
1e4a0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
1e4b0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
1e4c0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
1e4d0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
1e4e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
1e4f0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
1e500 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
1e510 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
1e520 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
1e530 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
1e540 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
1e550 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
1e560 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
1e570 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
1e580 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
1e590 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
1e5a0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
1e5b0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
1e5c0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
1e5d0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
1e5e0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 *.** ^A call to
1e5f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
1e600 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
1e610 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
1e620 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 uffer P..** ^If
1e630 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
1e640 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62 ne, then P can b
1e650 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
1e660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 ..**.** ^If this
1e670 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 routine has not
1e680 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 been previously
1e690 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 called or if th
1e6a0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 e previous.** ca
1e6b0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 ll had N less th
1e6c0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 an one, then the
1e6d0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 PRNG is seeded
1e6e0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
1e6f0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f .** obtained fro
1e700 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1e710 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
1e720 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
1e730 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
1e740 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 ^If the previou
1e750 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 s call to this r
1e760 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 outine had an N
1e770 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 of 1 or more the
1e780 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d n.** the pseudo-
1e790 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
1e7a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
1e7b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
1e7c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
1e7d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
1e7e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
1e7f0 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ethod..*/.SQLITE
1e800 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
1e810 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 3_randomness(int
1e820 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f N, void *P);../
1e830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1e840 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 ompile-Time Auth
1e850 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 orization Callba
1e860 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 cks.**.** ^This
1e870 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 routine register
1e880 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 s an authorizer
1e890 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 callback with a
1e8a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
1e8b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1e8c0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e on], supplied in
1e8d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
1e8e0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 ent..** ^The aut
1e8f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1e900 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
1e910 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
1e920 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 e being compiled
1e930 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
1e940 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
1e950 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 s variants [sqli
1e960 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1e970 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
1e980 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 repare16()] and
1e990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e9a0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 16_v2()]. ^At v
1e9b0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
1e9c0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
1e9d0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
1e9e0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
1e9f0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
1ea00 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
1ea10 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
1ea20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1ea30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
1ea40 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
1ea50 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
1ea60 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f wed. ^The autho
1ea70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
1ea80 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
1ea90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
1eaa0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
1eab0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1eac0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
1ead0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
1eae0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
1eaf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1eb00 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
1eb10 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
1eb20 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
1eb30 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
1eb40 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
1eb50 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
1eb60 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
1eb70 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 r. ^If the auth
1eb80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1eb90 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 returns.** any v
1eba0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 alue other than
1ebb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
1ebc0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 [SQLITE_OK], or
1ebd0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a [SQLITE_DENY].*
1ebe0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 * then the [sqli
1ebf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1ec00 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
1ec10 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
1ec20 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f red.** the autho
1ec30 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
1ec40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
1ec50 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ssage..**.** Whe
1ec60 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
1ec70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
1ec80 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 K], that means t
1ec90 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
1eca0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e requested is ok.
1ecb0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ^When the call
1ecc0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1ecd0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
1ece0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1ecf0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
1ed00 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
1ed10 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a t triggered the.
1ed20 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 ** authorizer wi
1ed30 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
1ed40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 error message ex
1ed50 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a plaining that.**
1ed60 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 access is denie
1ed70 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 d. .**.** ^The f
1ed80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1ed90 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1eda0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
1edb0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
1edc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
1edd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
1ede0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e _authorizer() in
1edf0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 terface. ^The se
1ee00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a cond parameter.*
1ee10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
1ee20 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
1ee30 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
1ee40 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
1ee50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
1ee60 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 e particular act
1ee70 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1ee80 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 ized. ^The third
1ee90 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 through sixth p
1eea0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
1eeb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 the callback are
1eec0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1eed0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f strings that co
1eee0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c ntain additional
1eef0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 .** details abou
1ef00 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 t the action to
1ef10 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a be authorized..*
1ef20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 *.** ^If the act
1ef30 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
1ef40 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 ITE_READ].** and
1ef50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1ef60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 turns [SQLITE_IG
1ef70 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a NORE] then the.*
1ef80 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1ef90 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 ement] statement
1efa0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 is constructed
1efb0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a to substitute.**
1efc0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
1efd0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
1efe0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
1eff0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 would have.** be
1f000 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
1f010 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
1f020 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b returned. The [
1f030 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a SQLITE_IGNORE].*
1f040 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 * return can be
1f050 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 used to deny an
1f060 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 untrusted user a
1f070 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 ccess to individ
1f080 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f ual.** columns o
1f090 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 f a table..** ^I
1f0a0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
1f0b0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c e is [SQLITE_DEL
1f0c0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c ETE] and the cal
1f0d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
1f0e0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1f0f0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 then the [DELET
1f100 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f E] operation pro
1f110 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a ceeds but the.**
1f120 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d [truncate optim
1f130 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 ization] is disa
1f140 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 bled and all row
1f150 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e s are deleted in
1f160 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a dividually..**.*
1f170 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 * An authorizer
1f180 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 is used when [sq
1f190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
1f1a0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 preparing].** SQ
1f1b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f L statements fro
1f1c0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 m an untrusted s
1f1d0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 ource, to ensure
1f1e0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 that the SQL st
1f1f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e atements.** do n
1f200 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 ot try to access
1f210 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e data they are n
1f220 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 ot allowed to se
1f230 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 e, or that they
1f240 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f do not.** try to
1f250 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f execute malicio
1f260 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 us statements th
1f270 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 at damage the da
1f280 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 tabase. For.**
1f290 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
1f2a0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f ication may allo
1f2b0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 w a user to ente
1f2c0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 r arbitrary.** S
1f2d0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 QL queries for e
1f2e0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 valuation by a d
1f2f0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 atabase. But th
1f300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
1f310 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 es.** not want t
1f320 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 he user to be ab
1f330 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 le to make arbit
1f340 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 rary changes to
1f350 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
1f360 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 An authorizer
1f370 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 could then be pu
1f380 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 t in place while
1f390 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 the.** user-ent
1f3a0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e ered SQL is bein
1f3b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1f3c0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 re | prepared] t
1f3d0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 hat.** disallows
1f3e0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 everything exce
1f3f0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 pt [SELECT] stat
1f400 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 ements..**.** Ap
1f410 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
1f420 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 need to process
1f430 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 SQL from untrust
1f440 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 ed sources.** mi
1f450 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 ght also conside
1f460 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 r lowering resou
1f470 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 rce limits using
1f480 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
1f490 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 )].** and limiti
1f4a0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 ng database size
1f4b0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f using the [max_
1f4c0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
1f4d0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 GMA].** in addit
1f4e0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 ion to using an
1f4f0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a authorizer..**.*
1f500 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c * ^(Only a singl
1f510 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e e authorizer can
1f520 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 be in place on
1f530 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
1f540 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 ction.** at a ti
1f550 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 me. Each call t
1f560 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
1f570 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 thorizer overrid
1f580 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f es the.** previo
1f590 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 us call.)^ ^Dis
1f5a0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 able the authori
1f5b0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e zer by installin
1f5c0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 g a NULL callbac
1f5d0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 k..** The author
1f5e0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 izer is disabled
1f5f0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a by default..**.
1f600 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
1f610 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 r callback must
1f620 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
1f630 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
1f640 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
1f650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
1f660 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 invoked the aut
1f670 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f680 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
1f690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f6a0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1f6b0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
1f6c0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
1f6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f6e0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
1f6f0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
1f700 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
1f710 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 ph..**.** ^When
1f720 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f730 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 _v2()] is used t
1f740 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 o prepare a stat
1f750 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 ement, the.** st
1f760 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 atement might be
1f770 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 re-prepared dur
1f780 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
1f790 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a p()] due to a .*
1f7a0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e * schema change.
1f7b0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 Hence, the app
1f7c0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
1f7d0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a ensure that the.
1f7e0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f ** correct autho
1f7f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
1f800 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 emains in place
1f810 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 during the [sqli
1f820 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
1f830 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 ** ^Note that th
1f840 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1f850 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1f860 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 only during.**
1f870 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f880 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1f890 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 nts. Authorizat
1f8a0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 ion is not.** pe
1f8b0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 rformed during s
1f8c0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 tatement evaluat
1f8d0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f ion in [sqlite3_
1f8e0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a step()], unless.
1f8f0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 ** as stated in
1f900 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 the previous par
1f910 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f agraph, sqlite3_
1f920 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a step() invokes.*
1f930 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 * sqlite3_prepar
1f940 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 e_v2() to reprep
1f950 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 are a statement
1f960 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 after a schema c
1f970 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 hange..*/.SQLITE
1f980 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1f990 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1f9a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
1f9b0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
1f9c0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
1f9d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
1f9e0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1f9f0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
1fa00 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
1fa10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1fa20 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
1fa30 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1fa40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1fa50 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1fa60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
1fa70 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
1fa80 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
1fa90 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
1faa0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
1fab0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
1fac0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
1fad0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
1fae0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
1faf0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
1fb00 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
1fb10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1fb20 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
1fb30 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
1fb40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
1fb50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
1fb60 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 * Note that SQLI
1fb70 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 TE_IGNORE is als
1fb80 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c o used as a [SQL
1fb90 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 ITE_ROLLBACK | r
1fba0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 eturn code].** f
1fbb0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
1fbc0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 _vtab_on_conflic
1fbd0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a t()] interface..
1fbe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1fbf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 E_DENY 1 /*
1fc00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 Abort the SQL st
1fc10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 atement with an
1fc20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
1fc30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 SQLITE_IGNORE 2
1fc40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f /* Don't allo
1fc50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f w access, but do
1fc60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 n't generate an
1fc70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 error */../*.**
1fc80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
1fc90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 izer Action Code
1fca0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
1fcb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1fcc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
1fcd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
1fce0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
1fcf0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
1fd00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 d to authorize c
1fd10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 ertain SQL state
1fd20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 ment actions. T
1fd30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
1fd40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
1fd50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
1fd60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 eger code that s
1fd70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 pecifies.** what
1fd80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 action is being
1fd90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
1fda0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 ese are the inte
1fdb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ger action codes
1fdc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 that.** the aut
1fdd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1fde0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a may be passed..
1fdf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 **.** These acti
1fe00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 on code values s
1fe10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 ignify what kind
1fe20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 of operation is
1fe30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 to be.** author
1fe40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 ized. The 3rd a
1fe50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 nd 4th parameter
1fe60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 s to the authori
1fe70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 zation.** callba
1fe80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c ck function will
1fe90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
1fea0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
1feb0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 on which of the
1fec0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 se.** codes is u
1fed0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
1fee0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 d parameter. ^(
1fef0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
1ff00 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 r to the.** auth
1ff10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1ff20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
1ff30 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 he database ("ma
1ff40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 in", "temp",.**
1ff50 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 etc.) if applica
1ff60 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 ble.)^ ^The 6th
1ff70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1ff80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ff90 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
1ffa0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
1ffb0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
1ffc0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
1ffd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
1ffe0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
1fff0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
20000 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
20010 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
20020 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 from.** top-leve
20030 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f l SQL code..*/./
20040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 *********** 3rd
20070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 ************ 4th
20080 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 ***********/.#d
20090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
200a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ATE_INDEX
200b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 1 /* Index
200c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
200d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
200e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
200f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 TE_TABLE
20100 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 2 /* Table N
20110 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20120 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20130 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
20140 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 E_TEMP_INDEX
20150 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 3 /* Index Na
20160 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
20170 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
20180 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
20190 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
201a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 4 /* Table Nam
201b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
201c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
201d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
201e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 TEMP_TRIGGER 5
201f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
20200 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20220 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
20230 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 EMP_VIEW 6
20240 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
20250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
20260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20270 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 SQLITE_CREATE_TR
20280 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 IGGER 7
20290 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
202a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
202b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
202c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 QLITE_CREATE_VIE
202d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 W 8
202e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
202f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20310 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 LITE_DELETE
20320 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 9 /
20330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20340 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20360 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 ITE_DROP_INDEX
20370 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 10 /*
20380 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
20390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
203a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
203b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 TE_DROP_TABLE
203c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 11 /*
203d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
203e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
203f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20400 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 E_DROP_TEMP_INDE
20410 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 X 12 /* I
20420 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
20430 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20450 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 _DROP_TEMP_TABLE
20460 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 13 /* Ta
20470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
20480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
204a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 DROP_TEMP_TRIGGE
204b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 R 14 /* Tri
204c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
204d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
204e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
204f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ROP_TEMP_VIEW
20500 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 15 /* View
20510 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
20520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
20530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
20540 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 OP_TRIGGER
20550 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 16 /* Trigg
20560 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
20570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
20580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 P_VIEW
205a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 17 /* View N
205b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
205c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
205d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 fine SQLITE_INSE
205e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
205f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 18 /* Table N
20600 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20610 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20620 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d ine SQLITE_PRAGM
20630 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
20640 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 19 /* Pragma N
20650 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 ame 1st arg
20660 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 or NULL */.#defi
20670 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 ne SQLITE_READ
20680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20690 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
206a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
206b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
206c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 e SQLITE_SELECT
206d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 21
206e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
206f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
20700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20710 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 SQLITE_TRANSACT
20720 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 ION 22
20730 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
20740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
20750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20760 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 SQLITE_UPDATE
20770 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 23
20780 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20790 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
207a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
207b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 QLITE_ATTACH
207c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 24
207d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 /* Filename
207e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
207f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20800 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 LITE_DETACH
20810 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 25 /
20820 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
20830 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20850 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 ITE_ALTER_TABLE
20860 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 26 /*
20870 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
20880 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
208a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 TE_REINDEX
208b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 27 /*
208c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
208d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
208e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
208f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 E_ANALYZE
20900 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 28 /* T
20910 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
20920 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
20930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20940 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 _CREATE_VTABLE
20950 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 29 /* Ta
20960 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
20970 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
20980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20990 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 DROP_VTABLE
209a0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 30 /* Tab
209b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
209c0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
209d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
209e0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 UNCTION
209f0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 31 /* NULL
20a00 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 Func
20a10 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 tion Name */.#
20a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 define SQLITE_SA
20a30 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 VEPOINT
20a40 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 32 /* Opera
20a50 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 tion Savep
20a60 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 oint Name */.#d
20a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
20a80 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
20a90 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
20aa0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 ger used */.#def
20ab0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 ine SQLITE_RECUR
20ac0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 SIVE
20ad0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 33 /* NULL
20ae0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
20af0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a */../*.*
20b00 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
20b10 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
20b20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a g Functions.**.*
20b30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
20b40 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
20b50 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ck functions tha
20b60 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f t can be used fo
20b70 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 r.** tracing and
20b80 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 profiling the e
20b90 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 xecution of SQL
20ba0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
20bb0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 * ^The callback
20bc0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
20bd0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 red by sqlite3_t
20be0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 race() is invoke
20bf0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 d at.** various
20c00 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 times when an SQ
20c10 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 L statement is b
20c20 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c eing run by [sql
20c30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
20c40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 ^The sqlite3_tr
20c50 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 ace() callback i
20c60 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 s invoked with a
20c70 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
20c80 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 of the.** SQL s
20c90 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 tatement text as
20ca0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
20cb0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
20cc0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 uting..** ^(Addi
20cd0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 tional sqlite3_t
20ce0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 race() callbacks
20cf0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
20d00 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 as each triggere
20d10 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 d subprogram is
20d20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 entered. The ca
20d30 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 llbacks for trig
20d40 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 gers.** contain
20d50 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d a UTF-8 SQL comm
20d60 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 ent that identif
20d70 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e ies the trigger.
20d80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 )^.**.** The [SQ
20d90 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f LITE_TRACE_SIZE_
20da0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 LIMIT] compile-t
20db0 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 ime option can b
20dc0 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a e used to limit.
20dd0 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 ** the length of
20de0 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 [bound paramete
20df0 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 r] expansion in
20e00 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 the output of sq
20e10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a lite3_trace()..*
20e20 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
20e30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
20e40 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
20e50 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
20e60 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
20e70 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
20e80 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 finishes. ^The
20e90 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
20ea0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
20eb0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
20ec0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 ent text and an
20ed0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c estimate of wall
20ee0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f -clock time.** o
20ef0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 f how long that
20f00 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 statement took t
20f10 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f o run. ^The pro
20f20 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a file callback.**
20f30 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 time is in unit
20f40 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 s of nanoseconds
20f50 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 , however the cu
20f60 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 rrent implementa
20f70 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 tion.** is only
20f80 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 capable of milli
20f90 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f second resolutio
20fa0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 n so the six lea
20fb0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a st significant.*
20fc0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 * digits in the
20fd0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 time are meaning
20fe0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 less. Future ve
20ff0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
21000 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 .** might provid
21010 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 e greater resolu
21020 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 tion on the prof
21030 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 iler callback.
21040 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 The.** sqlite3_p
21050 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f rofile() functio
21060 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 n is considered
21070 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
21080 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 is.** subject t
21090 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 o change in futu
210a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
210b0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
210c0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
210d0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
210e0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
210f0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
21100 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
21110 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
21120 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
21130 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c *sqlite3_profil
21140 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 e(sqlite3*,. v
21150 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 oid(*xProfile)(v
21160 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
21170 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 ,sqlite3_uint64)
21180 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
21190 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
211a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 Progress Callba
211b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 cks.**.** ^The s
211c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
211d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 handler(D,N,X,P)
211e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
211f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a s the callback.*
21200 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 * function X to
21210 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f be invoked perio
21220 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c dically during l
21230 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c ong running call
21240 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
21250 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 _exec()], [sqlit
21260 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b e3_step()] and [
21270 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
21280 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 e()] for.** data
21290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
212a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 D. An example u
212b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 se for this.** i
212c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b nterface is to k
212d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 eep a GUI update
212e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 d during a large
212f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 query..**.** ^T
21300 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 he parameter P i
21310 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
21320 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
21330 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a ameter to the .*
21340 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
21350 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 ion X. ^The par
21360 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 ameter N is the
21370 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 approximate numb
21380 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 er of .** [virtu
21390 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 al machine instr
213a0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 uctions] that ar
213b0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 e evaluated betw
213c0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a een successive.*
213d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
213e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e the callback X.
213f0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 ^If N is less
21400 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 than one then th
21410 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 e progress.** ha
21420 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 ndler is disable
21430 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 d..**.** ^Only a
21440 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 single progress
21450 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 handler may be
21460 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 defined at one t
21470 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 ime per.** [data
21480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
21490 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 ; setting a new
214a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
214b0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 cancels the.**
214c0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 old one. ^Setti
214d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 ng parameter X t
214e0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 o NULL disables
214f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
21500 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 dler..** ^The pr
21510 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 ogress handler i
21520 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 s also disabled
21530 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 by setting N to
21540 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 a value less.**
21550 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 than 1..**.** ^I
21560 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 f the progress c
21570 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
21580 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 non-zero, the op
21590 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e eration is.** in
215a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 terrupted. This
215b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 feature can be
215c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
215d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 t a.** "Cancel"
215e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 button on a GUI
215f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 progress dialog
21600 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 box..**.** The p
21610 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
21620 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
21630 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
21640 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
21650 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
21660 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
21670 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 nvoked the progr
21680 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
21690 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
216a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
216b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
216c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
216d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
216e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
216f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
21700 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
21710 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
21720 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 *.*/.SQLITE_API
21730 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f void sqlite3_pro
21740 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
21750 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
21760 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
21770 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
21780 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
21790 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
217a0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ection.**.** ^Th
217b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
217c0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
217d0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 base file as spe
217e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a cified by the .*
217f0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
21800 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 ent. ^The filena
21810 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
21820 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
21830 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
21840 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
21850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
21860 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
21870 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
21880 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
21890 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
218a0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f ^(A [database co
218b0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
218c0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
218d0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
218e0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
218f0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
21900 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
21910 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
21920 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
21930 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
21940 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
21950 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
21960 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
21970 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
21980 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
21990 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
219a0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
219b0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 ect.)^ ^(If the
219c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
219d0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
219e0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
219f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
21a00 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
21a10 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
21a20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
21a30 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 returned.)^ ^Th
21a40 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
21a50 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
21a60 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
21a70 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
21a80 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
21a90 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
21aa0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
21ab0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 n of the error f
21ac0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 ollowing a failu
21ad0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 re of any.** of
21ae0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e the sqlite3_open
21af0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a () routines..**.
21b00 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
21b10 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 encoding for the
21b20 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
21b30 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 e UTF-8 if.** sq
21b40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
21b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21b60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a ) is called and.
21b70 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 ** UTF-16 in the
21b80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
21b90 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 er if sqlite3_op
21ba0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a en16() is used..
21bb0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
21bc0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
21bd0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
21be0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
21bf0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
21c00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
21c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
21c20 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
21c30 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
21c40 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
21c50 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
21c60 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
21c70 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
21c80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
21c90 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
21ca0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
21cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
21cc0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
21cd0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
21ce0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
21cf0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
21d00 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
21d10 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
21d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
21d30 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d (The flags param
21d40 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 eter to.** sqlit
21d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e e3_open_v2() can
21d60 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
21d70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
21d80 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
21d90 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
21da0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
21db0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
21dc0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
21dd0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 _FULLMUTEX], [SQ
21de0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
21df0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 CACHE],.** [SQLI
21e00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
21e10 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 ACHE], and/or [S
21e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
21e30 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c flags:)^.**.** <
21e40 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 dl>.** ^(<dt>[SQ
21e50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
21e60 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LY]</dt>.** <dd>
21e70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
21e80 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f opened in read-o
21e90 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 nly mode. If th
21ea0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 e database does
21eb0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 not.** already e
21ec0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 xist, an error i
21ed0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
21ee0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
21ef0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
21f00 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
21f10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
21f20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
21f30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
21f40 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
21f50 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
21f60 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
21f70 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
21f80 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
21f90 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
21fa0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
21fb0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
21fc0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
21fd0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
21fe0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
21ff0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
22000 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
22010 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
22020 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c TE_OPEN_CREATE]<
22030 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
22040 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
22050 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
22060 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 nd writing, and
22070 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a is created if.**
22080 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 it does not alr
22090 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 eady exist. This
220a0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 is the behavior
220b0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 that is always
220c0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 used for.** sqli
220d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
220e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
220f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
22100 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 .**.** If the 3r
22110 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
22120 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22130 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
22140 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f he.** combinatio
22150 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f ns shown above o
22160 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
22170 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a ed with other.**
22180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
22190 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f ADONLY | SQLITE_
221a0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 OPEN_* bits].**
221b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
221c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
221d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 **.** ^If the [S
221e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
221f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c EX] flag is set,
22200 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
22210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
22220 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 opens in the mu
22230 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
22240 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c ading mode] as l
22250 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c ong as the singl
22260 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 e-thread.** mode
22270 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 has not been se
22280 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
22290 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
222a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 ^If the.** [SQ
222b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
222c0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
222d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
222e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
222f0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 ens.** in the se
22300 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
22310 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 ing mode] unless
22320 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 single-thread w
22330 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
22340 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d selected at com
22350 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
22360 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 rt-time..** ^The
22370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
22380 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 AREDCACHE] flag
22390 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
223a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
223b0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 o be.** eligible
223c0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 to use [shared
223d0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 cache mode], reg
223e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
223f0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
22400 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 .** cache is ena
22410 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 bled using [sqli
22420 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
22430 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 d_cache()]. ^Th
22440 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
22450 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
22460 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 flag causes the
22470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22480 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 ion to not.** pa
22490 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 rticipate in [sh
224a0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
224b0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 even if it is e
224c0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 nabled..**.** ^T
224d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
224e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
224f0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 pen_v2() is the
22500 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b name of the.** [
22510 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
22520 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
22530 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
22540 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
22550 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 that.** the new
22560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22570 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
22580 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
22590 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
225a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
225b0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 hen the default
225c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
225d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a ject is used..**
225e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
225f0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 name is ":memory
22600 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 :", then a priva
22610 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e te, temporary in
22620 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
22630 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 .** is created f
22640 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f or the connectio
22650 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d n. ^This in-mem
22660 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c ory database wil
22670 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a l vanish when.**
22680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
22690 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
226a0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ed. Future vers
226b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
226c0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 ight.** make use
226d0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 of additional s
226e0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 pecial filenames
226f0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 that begin with
22700 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 the ":" charact
22710 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 er..** It is rec
22720 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 ommended that wh
22730 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 en a database fi
22740 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 lename actually
22750 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a does begin with.
22760 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 ** a ":" charact
22770 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 er you should pr
22780 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d efix the filenam
22790 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d e with a pathnam
227a0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f e such as.** "./
227b0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 " to avoid ambig
227c0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 uity..**.** ^If
227d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
227e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
227f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
22800 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
22810 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
22820 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
22830 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 ^This private d
22840 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
22850 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
22860 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
22870 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
22880 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
22890 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 losed..**.** [[U
228a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 RI filenames in
228b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d sqlite3_open()]]
228c0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d <h3>URI Filenam
228d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 es</h3>.**.** ^I
228e0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d f [URI filename]
228f0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
22900 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 is enabled, and
22910 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
22920 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 ument.** begins
22930 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 with "file:", th
22940 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 en the filename
22950 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
22960 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a s a URI. ^URI.**
22970 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
22980 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 retation is enab
22990 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 led if the [SQLI
229a0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
229b0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 g is.** set in t
229c0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
229d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
229e0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 en_v2(), or if i
229f0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e t has.** been en
22a00 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 abled globally u
22a10 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
22a20 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 _CONFIG_URI] opt
22a30 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 ion with the.**
22a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
22a50 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 )] method or by
22a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
22a70 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d URI] compile-tim
22a80 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 e option..** As
22a90 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
22aa0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c n 3.7.7, URI fil
22ab0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
22ac0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
22ad0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 ff.** by default
22ae0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c , but future rel
22af0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 eases of SQLite
22b00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 might enable URI
22b10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 filename.** int
22b20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 erpretation by d
22b30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 efault. See "[U
22b40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 RI filenames]" f
22b50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
22b60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
22b70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
22b80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 s are parsed acc
22b90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 ording to RFC 39
22ba0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 86. ^If the URI
22bb0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 contains an.** a
22bc0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 uthority, then i
22bd0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 t must be either
22be0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
22bf0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a or the string .
22c00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 ** "localhost".
22c10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 ^If the authorit
22c20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 y is not an empt
22c30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 y string or "loc
22c40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 alhost", an .**
22c50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
22c60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e d to the caller.
22c70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 ^The fragment c
22c80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 omponent of a UR
22c90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e I, if .** presen
22ca0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a t, is ignored..*
22cb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
22cc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f s the path compo
22cd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 nent of the URI
22ce0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 as the name of t
22cf0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 he disk file.**
22d00 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 which contains t
22d10 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 he database. ^If
22d20 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 the path begins
22d30 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 with a '/' char
22d40 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 acter, .** then
22d50 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 it is interprete
22d60 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 d as an absolute
22d70 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 path. ^If the p
22d80 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 ath does not beg
22d90 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f in .** with a '/
22da0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 ' (meaning that
22db0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 the authority se
22dc0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ction is omitted
22dd0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a from the URI).*
22de0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 * then the path
22df0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
22e00 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 s a relative pat
22e10 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f h. .** ^On windo
22e20 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f ws, the first co
22e30 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 mponent of an ab
22e40 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 solute path .**
22e50 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 is a drive speci
22e60 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 fication (e.g. "
22e70 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f C:")..**.** [[co
22e80 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 re URI query par
22e90 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 ameters]].** The
22ea0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
22eb0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f of a URI may co
22ec0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 ntain parameters
22ed0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 that are interp
22ee0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 reted.** either
22ef0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 by SQLite itself
22f00 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c , or by a [VFS |
22f10 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c custom VFS impl
22f20 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 ementation]..**
22f30 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
22f40 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 s the following
22f50 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 three query para
22f60 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 meters:.**.** <u
22f70 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e l>.** <li> <b>
22f80 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 vfs</b>: ^The "v
22f90 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 fs" parameter ma
22fa0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 y be used to spe
22fb0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 cify the name of
22fc0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 .** a VFS ob
22fd0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 ject that provid
22fe0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
22ff0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
23000 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a e that should.**
23010 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 be used to
23020 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
23030 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b ase file on disk
23040 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f . ^If this optio
23050 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 n is set to.**
23060 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 an empty stri
23070 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 ng the default V
23080 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 FS object is use
23090 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 d. ^Specifying a
230a0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 n unknown.**
230b0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 VFS is an error
230c0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 . ^If sqlite3_op
230d0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
230e0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 and the vfs opti
230f0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 on is.** pre
23100 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 sent, then the V
23110 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 FS specified by
23120 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 the option takes
23130 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 precedence over
23140 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 .** the valu
23150 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
23160 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
23170 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
23180 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
23190 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a li> <b>mode</b>:
231a0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 ^(The mode para
231b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
231c0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c to either "ro",
231d0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 "rw",.** "r
231e0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 wc", or "memory"
231f0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 . Attempting to
23200 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 set it to any ot
23210 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 her value is.**
23220 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 an error)^.
23230 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
23240 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
23250 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
23260 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
23270 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
23280 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
23290 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
232a0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
232b0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
232c0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
232d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
232e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
232f0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 2(). ^If the mod
23300 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 e option is set
23310 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c to .** "rw",
23320 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
23330 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
23340 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 read-write (but
23350 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a not create) .**
23360 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 access, as
23370 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 if SQLITE_OPEN_R
23380 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f EADWRITE (but no
23390 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 t SQLITE_OPEN_CR
233a0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 EATE) had .**
233b0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c been set. ^Val
233c0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 ue "rwc" is equi
233d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
233e0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 g both .** S
233f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
23400 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f RITE and SQLITE_
23410 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 OPEN_CREATE. ^I
23420 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
23430 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 n is.** set
23440 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e to "memory" then
23450 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f a pure [in-memo
23460 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 ry database] tha
23470 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a t never reads.**
23480 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 or writes f
23490 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 rom disk is used
234a0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f . ^It is an erro
234b0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 r to specify a v
234c0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 alue for.**
234d0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
234e0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 er that is less
234f0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e restrictive than
23500 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 that specified
23510 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c by.** the fl
23520 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 ags passed in th
23530 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
23540 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
23550 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 n_v2()..**.**
23560 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 <li> <b>cache</b
23570 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 >: ^The cache pa
23580 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
23590 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 et to either "sh
235a0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 ared" or.**
235b0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 "private". ^Sett
235c0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 ing it to "share
235d0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 d" is equivalent
235e0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a to setting the.
235f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
23600 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 EN_SHAREDCACHE b
23610 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 it in the flags
23620 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
23630 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 to.** sqlite
23640 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 3_open_v2(). ^Se
23650 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 tting the cache
23660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 parameter to "pr
23670 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 ivate" is .**
23680 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 equivalent to
23690 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 setting the SQLI
236a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
236b0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 ACHE bit..**
236c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
236d0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
236e0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 nd the "cache" p
236f0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 arameter is pres
23700 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 ent in.** a
23710 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 URI filename, it
23720 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 s value override
23730 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 s any behavior r
23740 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 equested by sett
23750 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 ing.** SQLIT
23760 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
23770 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 CHE or SQLITE_OP
23780 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 EN_SHAREDCACHE f
23790 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a lag..** </ul>.**
237a0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 .** ^Specifying
237b0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d an unknown param
237c0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 eter in the quer
237d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
237e0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a URI is not an.*
237f0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 * error. Future
23800 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
23810 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 ite might unders
23820 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 tand additional
23830 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
23840 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 ers. See "[quer
23850 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 y parameters wit
23860 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e h special meanin
23870 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f g to SQLite]" fo
23880 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 r.** additional
23890 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
238a0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
238b0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 e examples]] <h3
238c0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 >URI filename ex
238d0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a amples</h3>.**.*
238e0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
238f0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 "1" align=center
23900 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a cellpadding=5>.
23910 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 ** <tr><th> URI
23920 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 filenames <th> R
23930 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 esults.** <tr><t
23940 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 d> file:data.db
23950 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
23960 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 Open the file
23970 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
23980 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
23990 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ry..** <tr><td>
239a0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
239b0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 data.db<br>.**
239c0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
239d0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
239e0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 b <br> .**
239f0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c file://local
23a00 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 host/home/fred/d
23a10 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e ata.db <br> <td>
23a20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
23a30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
23a40 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
23a50 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 /data.db"..** <t
23a60 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 r><td> file://da
23a70 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 rkstar/home/fred
23a80 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a /data.db <td> .*
23a90 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
23aa0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 ror. "darkstar"
23ab0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 is not a recogni
23ac0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a zed authority..*
23ad0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d * <tr><td style=
23ae0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 "white-space:now
23af0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 rap"> .**
23b00 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f file:///C:/Do
23b10 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 cuments%20and%20
23b20 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 Settings/fred/De
23b30 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a sktop/data.db.**
23b40 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 <td> Window
23b50 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 s only: Open the
23b60 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
23b70 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f on fred's deskto
23b80 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 p on drive.**
23b90 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 C:. Note
23ba0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 that the %20 esc
23bb0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 aping in this ex
23bc0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 ample is not str
23bd0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 ictly .**
23be0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 necessary - s
23bf0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 pace characters
23c00 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 can be used lite
23c10 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 rally.**
23c20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d in URI filenam
23c30 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 es..** <tr><td>
23c40 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
23c50 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 e=ro&cache=priva
23c60 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 te <td> .**
23c70 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
23c80 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
23c90 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
23ca0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 y for read-only
23cb0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 access..**
23cc0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f Regardless o
23cd0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
23ce0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f shared-cache mo
23cf0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 de is enabled by
23d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 .** def
23d10 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 ault, use a priv
23d20 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 ate cache..** <t
23d30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d r><td> file:/hom
23d40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 e/fred/data.db?v
23d50 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c fs=unix-nolock <
23d60 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 td>.**
23d70 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 Open file "/home
23d80 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 /fred/data.db".
23d90 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 Use the special
23da0 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b VFS "unix-nolock
23db0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 "..** <tr><td> f
23dc0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
23dd0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a =readonly <td> .
23de0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
23df0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 rror. "readonly"
23e00 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 is not a valid
23e10 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 option for the "
23e20 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e mode" parameter.
23e30 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a .** </table>.**.
23e40 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 ** ^URI hexadeci
23e50 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
23e60 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 nces (%HH) are s
23e70 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 upported within
23e80 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 the path and.**
23e90 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
23ea0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 of a URI. A hex
23eb0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
23ec0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 sequence consist
23ed0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e s of a.** percen
23ee0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 t sign - "%" - f
23ef0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 ollowed by exact
23f00 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d ly two hexadecim
23f10 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 al digits .** sp
23f20 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 ecifying an octe
23f30 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 t value. ^Before
23f40 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 the path or que
23f50 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
23f60 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 a.** URI filena
23f70 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 me are interpret
23f80 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 ed, they are enc
23f90 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 oded using UTF-8
23fa0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 and all .** hex
23fb0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
23fc0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 sequences replac
23fd0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 ed by a single b
23fe0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 yte containing t
23ff0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 he.** correspond
24000 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 ing octet. If th
24010 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 is process gener
24020 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 ates an invalid
24030 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a UTF-8 encoding,.
24040 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ** the results a
24050 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
24060 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
24070 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 indows users:</b
24080 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 > The encoding
24090 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c used for the fil
240a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a ename argument.*
240b0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 * of sqlite3_ope
240c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
240d0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 open_v2() must b
240e0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 e UTF-8, not wha
240f0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 tever.** codepag
24100 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 e is currently d
24110 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d efined. Filenam
24120 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e es containing in
24130 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 ternational.** c
24140 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 haracters must b
24150 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 e converted to U
24160 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 TF-8 prior to pa
24170 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a ssing them into.
24180 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
24190 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
241a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 n_v2()..**.** <b
241b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
241c0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c Runtime users:<
241d0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 /b> The tempora
241e0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 ry directory mus
241f0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f t be set.** prio
24200 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c r to calling sql
24210 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
24220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
24230 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 . Otherwise, va
24240 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 rious.** feature
24250 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 s that require t
24260 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 he use of tempor
24270 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 ary files may fa
24280 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c il..**.** See al
24290 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d so: [sqlite3_tem
242a0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a p_directory].*/.
242b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
242c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
242d0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
242e0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
242f0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
24300 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
24310 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
24320 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
24330 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
24340 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
24350 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
24360 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
24370 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
24380 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
24390 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
243a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
243b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
243c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
243d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
243e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
243f0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
24400 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
24410 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
24420 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
24430 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
24440 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
24450 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
24460 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
24470 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
24480 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
24490 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
244a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
244b0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
244c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
244d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 I3REF: Obtain Va
244e0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 lues For URI Par
244f0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 ameters.**.** Th
24500 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 ese are utility
24510 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c routines, useful
24520 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e to VFS implemen
24530 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 tations, that ch
24540 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 eck.** to see if
24550 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
24560 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 was a URI that
24570 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 contained a spec
24580 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 ific query .** p
24590 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 arameter, and if
245a0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 so obtains the
245b0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 value of that qu
245c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ery parameter..*
245d0 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 *.** If F is the
245e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
245f0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 me pointer passe
24600 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
24610 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a () method of .**
24620 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 a VFS implement
24630 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 ation when the f
24640 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
24650 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e o xOpen() has on
24660 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 e or .** more of
24670 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
24680 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 N_URI] or [SQLIT
24690 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 E_OPEN_MAIN_DB]
246a0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 bits set and.**
246b0 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 P is the name of
246c0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d the query param
246d0 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 eter, then.** sq
246e0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
246f0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
24700 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
24710 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 e P.** parameter
24720 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 if it exists or
24730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
24740 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 if P does not ap
24750 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 pear as a .** qu
24760 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e ery parameter on
24770 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 F. If P is a q
24780 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
24790 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 f F.** has no ex
247a0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 plicit value, th
247b0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
247c0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
247d0 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 turns.** a point
247e0 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 er to an empty s
247f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
24800 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
24810 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
24820 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ine assumes that
24830 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a P is a boolean.
24840 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 ** parameter and
24850 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
24860 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 ) or false (0) a
24870 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 ccording to the
24880 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 value.** of P.
24890 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
248a0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
248b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
248c0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a rue (1) if the.*
248d0 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 * value of query
248e0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
248f0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 one of "yes", "t
24900 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e rue", or "on" in
24910 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 any.** case or
24920 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
24930 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a ins with a non-z
24940 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 ero number. The
24950 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 .** sqlite3_uri
24960 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
24970 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 routines returns
24980 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 false (0) if th
24990 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 e value of.** qu
249a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
249b0 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 is one of "no",
249c0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 "false", or "off
249d0 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 " in any case or
249e0 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 .** if the value
249f0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
24a00 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 umeric zero. If
24a10 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 P is not a quer
24a20 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
24a30 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 n F or if the va
24a40 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 lue of P is does
24a50 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f not match any o
24a60 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 f the.** above,
24a70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
24a80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
24a90 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a returns (B!=0)..
24aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
24ab0 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 3_uri_int64(F,P,
24ac0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 D) routine conve
24ad0 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rts the value of
24ae0 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d P into a.** 64-
24af0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
24b00 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 er and returns t
24b10 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 hat integer, or
24b20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a D if P does not.
24b30 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 ** exist. If th
24b40 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
24b50 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
24b60 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c than an integer,
24b70 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 then.** zero is
24b80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a returned..** .*
24b90 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c * If F is a NULL
24ba0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 pointer, then s
24bb0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
24bc0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
24bd0 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 s NULL and.** sq
24be0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
24bf0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
24c00 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 B. If F is not
24c10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
24c20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 and.** is not a
24c30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 database file pa
24c40 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 thname pointer t
24c50 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 hat SQLite passe
24c60 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
24c70 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 .** VFS method,
24c80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
24c90 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e r of this routin
24ca0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 e is undefined a
24cb0 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 nd probably.** u
24cc0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 ndesirable..*/.S
24cd0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
24ce0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 char *sqlite3_ur
24cf0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 i_parameter(cons
24d00 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d t char *zFilenam
24d10 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
24d20 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 Param);.SQLITE_A
24d30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 PI int sqlite3_u
24d40 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 ri_boolean(const
24d50 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f char *zFile, co
24d60 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
24d70 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b , int bDefault);
24d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
24d90 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
24da0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 3_uri_int64(cons
24db0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 t char*, const c
24dc0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e har*, sqlite3_in
24dd0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t64);.../*.** CA
24de0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
24df0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
24e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
24e10 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e te3_errcode() in
24e20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
24e30 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 the numeric [res
24e40 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ult code] or.**
24e50 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
24e60 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
24e70 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 ost recent faile
24e80 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 d sqlite3_* API
24e90 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 call.** associat
24ea0 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ed with a [datab
24eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
24ec0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 If a prior API
24ed0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 call failed.** b
24ee0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ut the most rece
24ef0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 nt API call succ
24f00 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 eeded, the retur
24f10 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 n value from.**
24f20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
24f30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
24f40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
24f50 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
24f60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
24f70 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
24f80 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
24f90 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
24fa0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
24fb0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
24fc0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
24fd0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
24fe0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
24ff0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
25000 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
25010 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
25020 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
25030 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
25040 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
25050 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
25060 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
25070 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
25080 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
25090 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
250a0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
250b0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
250c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
250d0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
250e0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
250f0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
25100 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
25110 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
25120 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
25130 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
25140 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
25150 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
25160 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
25170 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
25180 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
25190 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
251a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
251b0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
251c0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
251d0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
251e0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
251f0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
25200 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
25210 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
25220 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
25230 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
25240 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
25250 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
25260 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
25270 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
25280 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
25290 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
252a0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
252b0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
252c0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
252d0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
252e0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
252f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
25300 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
25310 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
25320 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
25330 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
25340 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
25350 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
25360 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
25370 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
25380 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
25390 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
253a0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
253b0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
253c0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
253d0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
253e0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
253f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
25400 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
25410 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
25420 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
25430 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
25440 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
25450 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
25460 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
25470 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
25480 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
25490 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
254a0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
254b0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
254c0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
254d0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
254e0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
254f0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
25500 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
25510 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
25520 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
25530 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
25540 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
25550 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
25560 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
25570 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
25580 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
25590 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 set..*/.SQLITE_A
255a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
255b0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
255c0 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
255d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
255e0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
255f0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
25600 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
25610 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
25620 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
25630 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
25640 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
25650 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 g16(sqlite3*);.S
25660 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
25670 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
25680 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a rstr(int);../*.*
25690 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
256a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
256b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
256c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
256d0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 t} {prepared sta
256e0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 tements}.**.** A
256f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
25700 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
25710 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 ents a single SQ
25720 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 L statement..**
25730 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 This object is v
25740 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 ariously known a
25750 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 s a "prepared st
25760 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a atement" or a.**
25770 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 "compiled SQL s
25780 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d tatement" or sim
25790 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d ply as a "statem
257a0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent"..**.** The
257b0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d life of a statem
257c0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 ent object goes
257d0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 something like t
257e0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
257f0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
25800 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
25810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
25820 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 _v2()] or a rela
25830 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 ted.** func
25840 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 tion..** <li> Bi
25850 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f nd values to [ho
25860 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 st parameters] u
25870 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
25880 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
25890 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
258a0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
258b0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
258c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
258d0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
258e0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
258f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 he statement usi
25900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
25910 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
25920 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
25930 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
25940 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
25950 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
25960 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
25970 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
25980 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
25990 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f >.**.** Refer to
259a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f documentation o
259b0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 n individual met
259c0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 hods above for a
259d0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
259e0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 ormation..*/.typ
259f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
25a00 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
25a10 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
25a20 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
25a30 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 Limits.**.** ^(
25a40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
25a50 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
25a60 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
25a70 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
25a80 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
25a90 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
25aa0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
25ab0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
25ac0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
25ad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
25ae0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
25af0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
25b00 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
25b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
25b20 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
25b30 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
25b40 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
25b50 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
25b60 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
25b70 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
25b80 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
25b90 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
25ba0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
25bb0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uct.)^.**.** ^If
25bc0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
25bd0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
25be0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
25bf0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
25c00 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 ^(For each limit
25c10 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 category SQLITE
25c20 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f _LIMIT_<i>NAME</
25c30 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a i> there is a .*
25c40 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
25c50 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
25c60 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
25c70 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 time by a C prep
25c80 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 rocessor macro c
25c90 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 alled.** [limits
25ca0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 | SQLITE_MAX_<i
25cb0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 >NAME</i>]..** (
25cc0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
25cd0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
25ce0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
25cf0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 ))^.** ^Attempts
25d00 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
25d10 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
25d20 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
25d30 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
25d40 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
25d50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
25d60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 d..**.** ^Regard
25d70 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
25d80 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 or not the limit
25d90 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 was changed, th
25da0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c e .** [sqlite3_l
25db0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 imit()] interfac
25dc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 e returns the pr
25dd0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ior value of the
25de0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 limit..** ^Henc
25df0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 e, to find the c
25e00 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
25e10 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 a limit without
25e20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 changing it,.**
25e30 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 simply invoke th
25e40 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 is interface wit
25e50 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 h the third para
25e60 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e meter set to -1.
25e70 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 .**.** Run-time
25e80 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
25e90 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
25ea0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
25eb0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
25ec0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
25ed0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
25ee0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
25ef0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
25f00 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
25f10 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
25f20 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
25f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
25f40 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
25f50 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
25f60 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
25f70 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
25f80 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
25f90 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
25fa0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
25fb0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
25fc0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
25fd0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
25fe0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
25ff0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
26000 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
26010 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
26020 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
26030 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
26040 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
26050 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
26060 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
26070 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
26080 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
26090 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
260a0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
260b0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
260c0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
260d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
260e0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
260f0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
26100 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
26110 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
26120 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
26130 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
26140 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
26150 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
26160 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
26170 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
26180 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
26190 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
261a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
261b0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
261c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
261d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
261e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
261f0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
26200 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
26210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26220 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
26230 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
26240 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
26250 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
26260 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
26270 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
26280 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
26290 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
262a0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
262b0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
262c0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
262d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
262e0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
262f0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
26300 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
26310 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
26320 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
26330 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
26340 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
26350 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
26360 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
26370 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
26380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
26390 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
263a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
263b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
263c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
263d0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
263e0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 B or table row,
263f0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a in bytes.<dd>)^.
26400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26410 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d IMIT_SQL_LENGTH]
26420 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26430 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
26440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26450 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
26460 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
26470 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 nt, in bytes.</d
26480 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
26490 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
264a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
264b0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 LIMIT_COLUMN</dt
264c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
264d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
264e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c olumns in a tabl
264f0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 e definition or
26500 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 in the.** result
26510 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
26520 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 T] or the maximu
26530 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
26540 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
26550 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
26560 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
26570 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a clause.</dd>)^.
26580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26590 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d IMIT_EXPR_DEPTH]
265a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
265b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
265c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
265d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
265e0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
265f0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
26600 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
26610 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
26620 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d OMPOUND_SELECT]]
26630 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26640 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
26650 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
26660 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
26670 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
26680 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
26690 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
266a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
266b0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d E_LIMIT_VDBE_OP]
266c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
266d0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 IMIT_VDBE_OP</dt
266e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
266f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 imum number of i
26700 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 nstructions in a
26710 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
26720 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 program.** used
26730 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e to implement an
26740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
26750 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e This limit is n
26760 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 ot currently.**
26770 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 enforced, though
26780 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 that might be a
26790 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 dded in some fut
267a0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
267b0 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e * SQLite.</dd>)^
267c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
267d0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
267e0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 RG]] ^(<dt>SQLIT
267f0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
26800 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _ARG</dt>.** <dd
26810 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
26820 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
26830 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c on a function.<
26840 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
26850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
26860 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c CHED]] ^(<dt>SQL
26870 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
26880 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
26890 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
268a0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 r of [ATTACH | a
268b0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
268c0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a s].)^</dd>.**.**
268d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
268e0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
268f0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 GTH]].** ^(<dt>S
26900 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
26910 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c _PATTERN_LENGTH<
26920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26930 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
26940 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 f the pattern ar
26950 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c gument to the [L
26960 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 IKE] or.** [GLOB
26970 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 ] operators.</dd
26980 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
26990 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
269a0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 E_NUMBER]].** ^(
269b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
269c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
269d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
269e0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e maximum index n
269f0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 umber of any [pa
26a00 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 rameter] in an S
26a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a QL statement.)^.
26a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26a30 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
26a40 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
26a50 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
26a60 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
26a70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
26a80 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e pth of recursion
26a90 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f for triggers.</
26aa0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
26ab0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
26ac0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
26ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26ae0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
26af0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
26b00 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
26b10 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
26b20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
26b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26b40 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
26b50 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
26b60 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
26b70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
26b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
26b90 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
26ba0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
26bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
26bc0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
26bd0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
26be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
26bf0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
26c00 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
26c10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
26c20 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
26c30 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
26c40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
26c50 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
26c60 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
26c70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26c80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
26c90 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
26ca0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
26cb0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 _TRIGGER_DEPTH
26cc0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 10../*
26cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
26ce0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
26cf0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 tatement.** KEYW
26d00 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 ORDS: {SQL state
26d10 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a ment compiler}.*
26d20 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
26d30 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
26d40 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
26d50 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
26d60 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
26d70 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
26d80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
26d90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
26da0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c argument, "db",
26db0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
26dc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 connection] obta
26dd0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 ined from a.** p
26de0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
26df0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
26e00 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
26e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 e3_open_v2()] or
26e20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
26e30 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 n16()]. The dat
26e40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
26e50 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
26e60 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a een closed..**.*
26e70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
26e80 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 ument, "zSql", i
26e90 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
26ea0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 to be compiled,
26eb0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 encoded.** as ei
26ec0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
26ed0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 F-16. The sqlit
26ee0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 e3_prepare() and
26ef0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
26f00 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 _v2().** interfa
26f10 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 ces use UTF-8, a
26f20 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
26f30 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 re16() and sqlit
26f40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
26f50 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e ).** use UTF-16.
26f60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
26f70 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
26f80 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
26f90 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
26fa0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
26fb0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
26fc0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 nator. ^If nByte
26fd0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
26fe0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
26ff0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
27000 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
27010 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 d from zSql. ^W
27020 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e hen nByte is non
27030 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a -negative, the.*
27040 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e * zSql string en
27050 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 ds at either the
27060 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 first '\000' or
27070 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 '\u0000' charac
27080 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 ter or.** the nB
27090 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 yte-th byte, whi
270a0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
270b0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 st. If the calle
270c0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 r knows.** that
270d0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
270e0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
270f0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 nated, then ther
27100 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 e is a small.**
27110 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
27120 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e ntage to be gain
27130 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e ed by passing an
27140 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
27150 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 that.** is equa
27160 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 l to the number
27170 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
27180 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e input string <i>
27190 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a including</i>.**
271a0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 the nul-termina
271b0 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 tor bytes as thi
271c0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 s saves SQLite f
271d0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a rom having to.**
271e0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 make a copy of
271f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
27200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 ..**.** ^If pzTa
27210 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 il is not NULL t
27220 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d hen *pzTail is m
27230 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
27240 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a the first byte.*
27250 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f * past the end o
27260 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 f the first SQL
27270 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
27280 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
27290 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 es only.** compi
272a0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 le the first sta
272b0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 tement in zSql,
272c0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
272d0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a ft pointing to.*
272e0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 * what remains u
272f0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
27300 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 ^*ppStmt is lef
27310 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
27320 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
27330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
27340 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
27350 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
27360 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e ite3_step()]. ^
27370 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 If there is an e
27380 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 rror, *ppStmt is
27390 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e set.** to NULL.
273a0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 ^If the input
273b0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f text contains no
273c0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
273d0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a ut is an empty.*
273e0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f * string or a co
273f0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 mment) then *ppS
27400 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 tmt is set to NU
27410 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 LL..** The calli
27420 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 ng procedure is
27430 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
27440 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d deleting the com
27450 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 piled.** SQL sta
27460 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
27470 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
27480 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 ] after it has f
27490 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
274a0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e .** ppStmt may n
274b0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ot be NULL..**.*
274c0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 * ^On success, t
274d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
274e0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 re() family of r
274f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
27500 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f SQLITE_OK];.** o
27510 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
27520 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
27530 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
27540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
27550 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
27560 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
27570 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
27580 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
27590 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
275a0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
275b0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
275c0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
275d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
275e0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
275f0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
27600 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 uraged..** ^In t
27610 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
27620 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 es, the prepared
27630 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 statement.** th
27640 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 at is returned (
27650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
27660 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 t] object) conta
27670 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ins a copy of th
27680 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
27690 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 L text. This cau
276a0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ses the [sqlite3
276b0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 _step()] interfa
276c0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 ce to.** behave
276d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
276e0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a hree ways:.**.**
276f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a <ol>.** <li>.**
27700 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^If the databas
27710 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 e schema changes
27720 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 , instead of ret
27730 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 urning [SQLITE_S
27740 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 CHEMA] as it.**
27750 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 always used to d
27760 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 o, [sqlite3_step
27770 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ()] will automat
27780 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
27790 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 the SQL.** stat
277a0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f ement and try to
277b0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 run it again. A
277c0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 s many as [SQLIT
277d0 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 E_MAX_SCHEMA_RET
277e0 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 RY].** retries w
277f0 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 ill occur before
27800 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
27810 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 gives up and ret
27820 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a urns an error..*
27830 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
27840 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 i>.** ^When an e
27850 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 rror occurs, [sq
27860 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
27870 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 ll return one of
27880 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a the detailed.**
27890 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f [error codes] o
278a0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f r [extended erro
278b0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 r codes]. ^The
278c0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 legacy behavior
278d0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c was that.** [sql
278e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
278f0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
27900 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 generic [SQLITE
27910 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 _ERROR] result c
27920 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 ode.** and the a
27930 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 pplication would
27940 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 have to make a
27950 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b second call to [
27960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
27970 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 .** in order to
27980 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 find the underly
27990 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 ing cause of the
279a0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 problem. With t
279b0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a he "v2" prepare.
279c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 ** interfaces, t
279d0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 he underlying re
279e0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 ason for the err
279f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 or is returned i
27a00 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c mmediately..** <
27a10 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
27a20 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 ** ^If the speci
27a30 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 fic value bound
27a40 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 to [parameter |
27a50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 host parameter]
27a60 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 in the .** WHERE
27a70 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e clause might in
27a80 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 fluence the choi
27a90 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
27aa0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 for a statement
27ab0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 ,.** then the st
27ac0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 atement will be
27ad0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
27ae0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 compiled, as if
27af0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a there had been .
27b00 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e ** a schema chan
27b10 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 ge, on the first
27b20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 [sqlite3_step(
27b30 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e )] call followin
27b40 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 g any change.**
27b50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
27b60 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 bind_text | bind
27b70 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 ings] of that [p
27b80 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e arameter]. .** ^
27b90 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c The specific val
27ba0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 ue of WHERE-clau
27bb0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d se [parameter] m
27bc0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
27bd0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 he .** choice of
27be0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 query plan if t
27bf0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
27c00 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 the left-hand si
27c10 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a de of a [LIKE].*
27c20 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 * or [GLOB] oper
27c30 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 ator or if the p
27c40 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 arameter is comp
27c50 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 ared to an index
27c60 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 ed column.** and
27c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 the [SQLITE_ENA
27c80 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 BLE_STAT3] compi
27c90 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
27ca0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f s enabled..** </
27cb0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a li>.** </ol>.*/.
27cc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
27cd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
27ce0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
27cf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
27d00 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
27d10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
27d20 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
27d30 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
27d40 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
27d50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
27d60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
27d70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
27d80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
27d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
27da0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
27db0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
27dc0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
27dd0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
27de0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
27df0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
27e00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
27e10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
27e20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
27e30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
27e40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
27e50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
27e60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
27e70 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
27e80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
27e90 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
27ea0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
27eb0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
27ec0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
27ed0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
27ee0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
27ef0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
27f00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
27f10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
27f20 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
27f30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
27f40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
27f50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
27f60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
27f70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
27f80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
27f90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
27fa0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
27fb0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
27fc0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
27fd0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
27fe0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
27ff0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
28000 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
28010 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
28020 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
28030 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
28040 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
28050 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
28060 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
28070 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
28080 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
28090 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
280a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
280b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
280c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
280d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
280e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
280f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
28100 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
28110 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
28120 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
28130 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
28140 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
28150 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
28160 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
28170 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
28180 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
28190 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
281a0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
281b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
281c0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
281d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
281e0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
281f0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
28200 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
28210 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 REF: Retrieving
28220 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a Statement SQL.**
28230 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 .** ^This interf
28240 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
28250 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
28260 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
28270 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
28280 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
28290 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
282a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
282b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
282c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
282d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
282e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
282f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
28300 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f pare16_v2()]..*/
28310 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
28320 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
28330 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
28340 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
28350 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
28360 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
28370 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 tatement Writes
28380 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a The Database.**.
28390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
283a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
283b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
283c0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
283d0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
283e0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
283f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
28400 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
28410 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
28420 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
28430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
28440 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
28450 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
28460 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
28470 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
28480 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
28490 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
284a0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
284b0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
284c0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
284d0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
284e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
284f0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
28500 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
28510 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
28520 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
28530 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
28540 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
28550 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
28560 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
28570 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
28580 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
28590 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
285a0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
285b0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
285c0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
285d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
285e0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
285f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
28600 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
28610 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
28620 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
28630 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
28640 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
28650 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
28660 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
28670 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
28680 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
28690 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
286a0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
286b0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
286c0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
286d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
286e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
286f0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
28700 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
28710 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
28720 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
28730 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
28740 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
28750 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
28760 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
28770 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
28780 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
28790 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
287a0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
287b0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
287c0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
287d0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
287e0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
287f0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
28800 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
28810 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
28820 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
28830 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
28840 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
28850 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
28860 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
28870 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
28880 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
28890 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 n disk..*/.SQLIT
288a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
288b0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
288c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
288d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
288e0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
288f0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 If A Prepared S
28900 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 tatement Has Bee
28910 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 n Reset.**.** ^T
28920 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
28930 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
28940 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
28950 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
28960 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
28970 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
28980 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
28990 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
289a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
289b0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f p(S)] but has no
289c0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 t run to complet
289d0 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e ion and/or has n
289e0 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 ot .** been rese
289f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
28a00 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 _reset(S)]. ^Th
28a10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
28a20 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 usy(S).** interf
28a30 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 ace returns fals
28a40 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c e if S is a NULL
28a50 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 pointer. If S
28a60 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c is not a .** NUL
28a70 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 L pointer and is
28a80 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 not a pointer t
28a90 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 o a valid [prepa
28aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
28ab0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 * object, then t
28ac0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
28ad0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
28ae0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
28af0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
28b00 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
28b10 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 sed in combinati
28b20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 on [sqlite3_next
28b30 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c _stmt()].** to l
28b40 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 ocate all prepar
28b50 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 ed statements as
28b60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
28b70 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e database .** con
28b80 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 nection that are
28b90 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e in need of bein
28ba0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 g reset. This c
28bb0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 an be used,.** f
28bc0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 or example, in d
28bd0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e iagnostic routin
28be0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 es to search for
28bf0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 prepared .** st
28c00 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 atements that ar
28c10 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e e holding a tran
28c20 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f saction open..*/
28c30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
28c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
28c50 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 y(sqlite3_stmt*)
28c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28c70 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
28c80 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
28c90 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
28ca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
28cb0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 3_value} {unprot
28cc0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28cd0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 lue}.**.** SQLit
28ce0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 e uses the sqlit
28cf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
28d00 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c to represent all
28d10 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
28d20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e can be stored in
28d30 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
28d40 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 e. SQLite uses d
28d50 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a ynamic typing.**
28d60 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 for the values
28d70 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c it stores. ^Val
28d80 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
28d90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28da0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
28db0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
28dc0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
28dd0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
28de0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
28df0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
28e00 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
28e10 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
28e20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
28e30 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
28e40 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
28e50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
28e60 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
28e70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
28e80 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
28e90 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
28ea0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
28eb0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
28ec0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
28ed0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
28ee0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
28ef0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
28f00 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
28f10 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
28f20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
28f30 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 _value..**.** Th
28f40 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 e terms "protect
28f50 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 ed" and "unprote
28f60 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 cted" refer to w
28f70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a hether or not.**
28f80 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 a mutex is held
28f90 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d . An internal m
28fa0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
28fb0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 a protected.**
28fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
28fd0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 ject but no mute
28fe0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e x is held for an
28ff0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
29000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29010 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 ject. If SQLite
29020 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 is compiled to
29030 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 be single-thread
29040 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c ed.** (with [SQL
29050 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
29060 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 ] and with [sqli
29070 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
29080 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a ] returning 0).*
29090 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 * or if SQLite i
290a0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 s run in one of
290b0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f reduced mutex mo
290c0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f des .** [SQLITE_
290d0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
290e0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f EAD] or [SQLITE_
290f0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
29100 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 AD].** then ther
29110 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 e is no distinct
29120 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
29130 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
29140 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
29150 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 _value objects a
29160 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 nd they can be u
29170 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 sed interchangea
29180 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a bly. However,.*
29190 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f * for maximum co
291a0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 de portability i
291b0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
291c0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
291d0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 ns.** still make
291e0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
291f0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
29200 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
29210 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
29220 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e lue objects even
29230 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 when not strict
29240 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a ly required..**.
29250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
29260 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 value objects th
29270 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 at are passed as
29280 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f parameters into
29290 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
292a0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 tation of [appli
292b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
292c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 QL functions] ar
292d0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 e protected..**
292e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
292f0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ue object return
29300 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
29310 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
29320 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 ] is unprotected
29330 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 ..** Unprotected
29340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
29350 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 bjects may only
29360 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 be used with.**
29370 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
29380 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
29390 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
293a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ()]..** The [sql
293b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 ite3_value_blob
293c0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f | sqlite3_value_
293d0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f type()] family o
293e0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 f.** interfaces
293f0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 require protecte
29400 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
29410 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 objects..*/.type
29420 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 def struct Mem s
29430 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f qlite3_value;../
29440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
29450 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 QL Function Cont
29460 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ext Object.**.**
29470 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 The context in
29480 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e which an SQL fun
29490 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 ction executes i
294a0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a s stored in an.*
294b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 * sqlite3_contex
294c0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f t object. ^A po
294d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 inter to an sqli
294e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
294f0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ct.** is always
29500 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
29510 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d to [application-
29520 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
29530 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 tions]..** The a
29540 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
29550 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
29560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
29570 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a ill pass this.**
29580 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 pointer through
29590 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b into calls to [
295a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
295b0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 nt | sqlite3_res
295c0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ult()],.** [sqli
295d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
295e0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 ntext()], [sqlit
295f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c e3_user_data()],
29600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
29610 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
29620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ], [sqlite3_get_
29630 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 auxdata()],.** a
29640 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 nd/or [sqlite3_s
29650 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a et_auxdata()]..*
29660 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
29670 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
29680 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
29690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
296a0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 F: Binding Value
296b0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 s To Prepared St
296c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 atements.** KEYW
296d0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 ORDS: {host para
296e0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 meter} {host par
296f0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 ameters} {host p
29700 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a arameter name}.*
29710 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
29720 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c parameter} {SQL
29730 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 parameters} {pa
29740 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d rameter binding}
29750 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 .**.** ^(In the
29760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
29770 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c xt input to [sql
29780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
29790 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 )] and its varia
297a0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 nts,.** literals
297b0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 may be replaced
297c0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 by a [parameter
297d0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f ] that matches o
297e0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a ne of following.
297f0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a ** templates:.**
29800 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
29810 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
29820 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
29830 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
29840 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
29850 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
29860 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 e templates abov
29870 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 e, NNN represent
29880 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
29890 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
298a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 represents an a
298b0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e lphanumeric iden
298c0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 tifier.)^ ^The
298d0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
298e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
298f0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
29900 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
29910 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
29920 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
29930 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
29940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
29950 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
29960 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
29970 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
29980 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
29990 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
299a0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
299b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
299c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
299d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
299e0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
299f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
29a00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
29a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
29a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
29a30 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
29a40 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
29a50 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
29a60 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
29a70 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
29a80 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
29a90 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
29aa0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
29ab0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
29ac0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
29ad0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
29ae0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
29af0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
29b00 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
29b10 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
29b20 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
29b30 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
29b40 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
29b50 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
29b60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
29b70 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
29b80 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
29b90 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
29ba0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
29bb0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
29bc0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
29bd0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
29be0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
29bf0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
29c00 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
29c10 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
29c20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
29c30 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
29c40 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
29c50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
29c60 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
29c70 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
29c80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 meter..** ^If th
29c90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
29ca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
29cb0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
29cc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
29cd0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
29ce0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 bind_blob() is a
29cf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
29d00 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 en the fourth pa
29d10 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 rameter.** is ig
29d20 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e nored and the en
29d30 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 d result is the
29d40 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f same as sqlite3_
29d50 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a bind_null()..**.
29d60 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f ** ^(In those ro
29d70 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 utines that have
29d80 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 a fourth argume
29d90 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 nt, its value is
29da0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
29db0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 f bytes in the p
29dc0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 arameter. To be
29dd0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 clear: the valu
29de0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
29df0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f er of <u>bytes</
29e00 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c u> in the value,
29e10 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
29e20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e of characters.)^
29e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 .** ^If the four
29e40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
29e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
29e60 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
29e70 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
29e80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
29e90 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 n the length of
29ea0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
29eb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
29ec0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
29ed0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
29ee0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ator..** If the
29ef0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
29f00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
29f10 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 _blob() is negat
29f20 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ive, then.** the
29f30 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
29f40 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 efined..** If a
29f50 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 non-negative fou
29f60 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
29f70 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c provided to sql
29f80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
29f90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
29fa0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 ind_text16() the
29fb0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 n that parameter
29fc0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 must be the byt
29fd0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 e offset.** wher
29fe0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e e the NUL termin
29ff0 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 ator would occur
2a000 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 assuming the st
2a010 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a ring were NUL.**
2a020 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 terminated. If
2a030 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 any NUL charact
2a040 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 ers occur at byt
2a050 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 e offsets less t
2a060 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 han .** the valu
2a070 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 e of the fourth
2a080 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 parameter then t
2a090 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
2a0a0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a ing value will.*
2a0b0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 * contain embedd
2a0c0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 ed NULs. The re
2a0d0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
2a0e0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 ons involving st
2a0f0 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d rings.** with em
2a100 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
2a110 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2a120 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
2a130 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
2a140 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 ind_blob(), sqli
2a150 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
2a160 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
2a170 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 bind_text16() is
2a180 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 a destructor us
2a190 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ed to dispose of
2a1a0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 the BLOB or.**
2a1b0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c string after SQL
2a1c0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 ite has finished
2a1d0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 with it. ^The
2a1e0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
2a1f0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f lled.** to dispo
2a200 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
2a210 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 r string even if
2a220 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c the call to sql
2a230 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
2a240 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e ,.** sqlite3_bin
2a250 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c d_text(), or sql
2a260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2a270 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e () fails. .** ^
2a280 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
2a290 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
2a2a0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
2a2b0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
2a2c0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
2a2d0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
2a2e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
2a2f0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
2a300 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
2a310 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
2a320 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 freed..** ^If t
2a330 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2a340 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 t has the value
2a350 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
2a360 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 T], then.** SQLi
2a370 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e te makes its own
2a380 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
2a390 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 the data immedi
2a3a0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a ately, before.**
2a3b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
2a3c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 d_*() routine re
2a3d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 turns..**.** ^Th
2a3e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
2a3f0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
2a400 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
2a410 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
2a420 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
2a430 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 h zeroes. ^A ze
2a440 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
2a450 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
2a460 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
2a470 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
2a480 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
2a490 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
2a4a0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
2a4b0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
2a4c0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
2a4d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
2a4e0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
2a4f0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
2a500 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
2a510 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
2a520 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
2a530 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
2a540 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 nes..** ^A negat
2a550 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
2a560 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
2a570 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
2a580 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
2a590 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 ^If any of the s
2a5a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2a5b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2a5c0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
2a5d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 pointer.** for t
2a5e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2a5f0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 tement] or with
2a600 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2a610 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a ment for which.*
2a620 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2a630 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
2a640 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 ed more recently
2a650 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 than [sqlite3_r
2a660 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e eset()],.** then
2a670 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 the call will r
2a680 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 eturn [SQLITE_MI
2a690 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 SUSE]. If any s
2a6a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a qlite3_bind_().*
2a6b0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 * routine is pas
2a6c0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 sed a [prepared
2a6d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2a6e0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
2a6f0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c ed, the.** resul
2a700 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 t is undefined a
2a710 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d nd probably harm
2a720 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 ful..**.** ^Bind
2a730 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
2a740 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
2a750 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
2a760 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 utine..** ^Unbou
2a770 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 nd parameters ar
2a780 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
2a790 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NULL..**.** ^Th
2a7a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2a7b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2a7c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2a7d0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a success or an.**
2a7e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
2a7f0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 anything goes w
2a800 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 rong..** ^[SQLIT
2a810 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
2a820 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
2a830 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
2a840 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
2a850 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d ^[SQLITE_NOMEM]
2a860 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2a870 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
2a880 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2a890 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2a8a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2a8b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2a8c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2a8d0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
2a8e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2a8f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
2a900 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2a910 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
2a920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2a930 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
2a940 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
2a950 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2a960 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a970 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 bind_double(sqli
2a980 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2a990 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f double);.SQLITE_
2a9a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a9b0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
2a9c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
2a9d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2a9e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
2a9f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
2aa00 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
2aa10 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f _int64);.SQLITE_
2aa20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2aa30 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
2aa40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 3_stmt*, int);.S
2aa50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2aa60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2aa70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2aa80 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
2aa90 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
2aaa0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2aab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2aac0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
2aad0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2aae0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2aaf0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2ab00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2ab10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 t sqlite3_bind_v
2ab20 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2ab30 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
2ab40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2ab50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2ab60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
2ab70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2ab80 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b t*, int, int n);
2ab90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2aba0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 : Number Of SQL
2abb0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
2abc0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 ^This routine c
2abd0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 an be used to fi
2abe0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
2abf0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 [SQL parameters
2ac00 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 ].** in a [prepa
2ac10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2ac20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
2ac30 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 are tokens of th
2ac40 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 e.** form "?", "
2ac50 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 ?NNN", ":AAA", "
2ac60 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 $AAA", or "@AAA"
2ac70 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a that serve as.*
2ac80 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 * placeholders f
2ac90 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 or values that a
2aca0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 re [sqlite3_bind
2acb0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a _blob | bound].*
2acc0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 * to the paramet
2acd0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 ers at a later t
2ace0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ime..**.** ^(Thi
2acf0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
2ad00 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
2ad10 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
2ad20 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
2ad30 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
2ad40 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
2ad50 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
2ad60 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
2ad70 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2ad80 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
2ad90 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
2ada0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
2adb0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a form are used,.*
2adc0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 * there may be g
2add0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e aps in the list.
2ade0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
2adf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2ae00 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2ae10 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2ae20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2ae30 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
2ae40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2ae50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2ae60 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2ae70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
2ae80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2ae90 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
2aea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2aeb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f EF: Name Of A Ho
2aec0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a st Parameter.**.
2aed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2aee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2aef0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 ame(P,N) interfa
2af00 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 ce returns.** th
2af10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d e name of the N-
2af20 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 th [SQL paramete
2af30 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 r] in the [prepa
2af40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2af50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d ..** ^(SQL param
2af60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
2af70 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 m "?NNN" or ":AA
2af80 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
2af90 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 "$AAA".** have a
2afa0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 name which is t
2afb0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 he string "?NNN"
2afc0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
2afd0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
2afe0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a * respectively..
2aff0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ** In other word
2b000 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 s, the initial "
2b010 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 :" or "$" or "@"
2b020 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e or "?".** is in
2b030 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f cluded as part o
2b040 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a f the name.)^.**
2b050 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 ^Parameters of
2b060 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 the form "?" wit
2b070 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 hout a following
2b080 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f integer have no
2b090 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 name.** and are
2b0a0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 referred to as
2b0b0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 "nameless" or "a
2b0c0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
2b0d0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ers"..**.** ^The
2b0e0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 first host para
2b0f0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
2b100 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a ex of 1, not 0..
2b110 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 **.** ^If the va
2b120 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 lue N is out of
2b130 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 range or if the
2b140 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 N-th parameter i
2b150 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 s.** nameless, t
2b160 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 hen NULL is retu
2b170 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 rned. ^The retu
2b180 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
2b190 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d * always in UTF-
2b1a0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 8 encoding even
2b1b0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 if the named par
2b1c0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 ameter was.** or
2b1d0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 iginally specifi
2b1e0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
2b1f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2b200 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 16()] or.** [sql
2b210 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2b220 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
2b230 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
2b240 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2b250 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
2b260 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2b270 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
2b280 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
2b290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2b2a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
2b2b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2b2c0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 *sqlite3_bind_p
2b2d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 arameter_name(sq
2b2e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b2f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b300 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 EF: Index Of A P
2b310 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 arameter With A
2b320 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a Given Name.**.**
2b330 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
2b340 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
2b350 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
2b360 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
2b370 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
2b380 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
2b390 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
2b3a0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
2b3b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2b3c0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2b3d0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
2b3e0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
2b3f0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
2b400 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
2b410 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
2b420 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
2b430 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
2b440 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
2b450 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
2b460 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
2b470 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
2b480 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
2b490 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2b4a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2b4b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2b4c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2b4d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2b4e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2b4f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2b500 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2b510 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2b520 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
2b530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2b540 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2b550 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
2b560 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
2b570 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
2b580 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
2b590 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
2b5a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2b5b0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 ment.**.** ^Cont
2b5c0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
2b5d0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
2b5e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2b5f0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
2b600 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
2b610 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
2b620 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
2b630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2b640 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f .** ^Use this ro
2b650 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
2b660 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
2b670 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 rs to NULL..*/.S
2b680 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2b690 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
2b6a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
2b6b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2b6c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
2b6d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
2b6e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 ult Set.**.** ^R
2b6f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
2b700 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2b710 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
2b720 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2b730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b740 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 ment]. ^This rou
2b750 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
2b760 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
2b770 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
2b780 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
2b790 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
2b7a0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
2b7b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
2b7c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 so: [sqlite3_dat
2b7d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 a_count()].*/.SQ
2b7e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2b7f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2b800 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2b810 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2b820 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 API3REF: Column
2b830 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c Names In A Resul
2b840 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 t Set.**.** ^The
2b850 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
2b860 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 rn the name assi
2b870 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 gned to a partic
2b880 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 ular column.** i
2b890 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
2b8a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
2b8b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 tatement. ^The
2b8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2b8d0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ame().** interfa
2b8e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2b8f0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2b900 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
2b910 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 string.** and sq
2b920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2b930 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 e16() returns a
2b940 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2b950 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
2b960 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
2b970 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
2b980 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 eter is the [pre
2b990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b9a0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 .** that impleme
2b9b0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d nts the [SELECT]
2b9c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 statement. ^The
2b9d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2b9e0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r is the.** colu
2b9f0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 mn number. ^The
2ba00 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
2ba10 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
2ba20 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2ba30 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
2ba40 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
2ba50 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 either the [prep
2ba60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2ba70 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ** is destroyed
2ba80 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 by [sqlite3_fina
2ba90 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
2baa0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2bab0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a s automatically.
2bac0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 ** reprepared by
2bad0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
2bae0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2baf0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 ()] for a partic
2bb00 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 ular run.** or u
2bb10 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
2bb20 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
2bb30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
2bb40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2bb50 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
2bb60 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
2bb70 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
2bb80 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 malloc() fails d
2bb90 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 uring the proces
2bba0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 sing of either r
2bbb0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 outine.** (for e
2bbc0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 xample during a
2bbd0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 conversion from
2bbe0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 UTF-8 to UTF-16)
2bbf0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 then a.** NULL
2bc00 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
2bc10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2bc20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 name of a result
2bc30 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 column is the v
2bc40 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 alue of the "AS"
2bc50 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 clause for.** t
2bc60 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 hat column, if t
2bc70 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c here is an AS cl
2bc80 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 ause. If there
2bc90 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a is no AS clause.
2bca0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 ** then the name
2bcb0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
2bcc0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e s unspecified an
2bcd0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f d may change fro
2bce0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 m.** one release
2bcf0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 of SQLite to th
2bd00 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 e next..*/.SQLIT
2bd10 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2bd20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2bd30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2bd40 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c mt*, int N);.SQL
2bd50 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2bd60 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2bd70 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
2bd80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
2bd90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2bda0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
2bdb0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
2bdc0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 lt.**.** ^These
2bdd0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 routines provide
2bde0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 a means to dete
2bdf0 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 rmine the databa
2be00 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a se, table, and.*
2be10 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 * table column t
2be20 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 hat is the origi
2be30 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 n of a particula
2be40 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 r result column
2be50 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 in.** [SELECT] s
2be60 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 tatement..** ^Th
2be70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
2be80 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
2be90 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
2bea0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
2beb0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
2bec0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
2bed0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 ^The _database
2bee0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2bef0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
2bf00 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 e name, the _tab
2bf10 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 le_ routines ret
2bf20 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 urn the table na
2bf30 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f me, and.** the o
2bf40 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 rigin_ routines
2bf50 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d return the colum
2bf60 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 n name..** ^The
2bf70 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2bf80 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
2bf90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2bfa0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 tement] is destr
2bfb0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 oyed.** using [s
2bfc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2bfd0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
2bfe0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
2bff0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
2c000 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
2c010 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
2c020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
2c030 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
2c040 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
2c050 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
2c060 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
2c070 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
2c080 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
2c090 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e ng..**.** ^The n
2c0a0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 ames returned ar
2c0b0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 e the original u
2c0c0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 n-aliased names
2c0d0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 of the.** databa
2c0e0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 se, table, and c
2c0f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 olumn..**.** ^Th
2c100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2c110 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
2c120 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 aces is a [prepa
2c130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2c140 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
2c150 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
2c160 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
2c170 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
2c180 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a mn returned by.*
2c190 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c * the statement,
2c1a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
2c1b0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
2c1c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
2c1d0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 e left-most colu
2c1e0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 mn is column 0 f
2c1f0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 or these routine
2c200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 s..**.** ^If the
2c210 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
2c220 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
2c230 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
2c240 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 ession or.** sub
2c250 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
2c260 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
2c270 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
2c280 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
2c290 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 urn.** NULL. ^T
2c2a0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
2c2b0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
2c2c0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
2c2d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
2c2e0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 .** occurs. ^Ot
2c2f0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 herwise, they re
2c300 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 turn the name of
2c310 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 the attached da
2c320 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a tabase, table,.*
2c330 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 * or column that
2c340 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f query result co
2c350 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 lumn was extract
2c360 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e ed from..**.** ^
2c370 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
2c380 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
2c390 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 hose whose names
2c3a0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 end with "16" r
2c3b0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 eturn.** UTF-16
2c3c0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 encoded strings
2c3d0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 and the other fu
2c3e0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
2c3f0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 TF-8..**.** ^The
2c400 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 se APIs are only
2c410 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
2c420 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
2c430 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
2c440 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
2c450 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 E_COLUMN_METADAT
2c460 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f A] C-preprocesso
2c470 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 r symbol..**.**
2c480 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
2c490 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
2c4a0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
2c4b0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
2c4c0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
2c4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c4e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
2c4f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
2c500 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
2c510 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
2c520 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
2c530 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
2c540 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a l one or more.**
2c550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c560 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
2c570 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
2c580 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
2c590 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 for the same [pr
2c5a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c5b0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
2c5c0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 umn.** at the sa
2c5d0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
2c5e0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2c5f0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 efined..*/.SQLIT
2c600 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2c610 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2c620 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
2c630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2c640 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2c650 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2c660 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2c670 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
2c680 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2c690 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2c6a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2c6b0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 mn_table_name(sq
2c6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2c6d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2c6e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2c6f0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
2c700 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2c710 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2c720 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2c730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
2c740 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
2c750 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2c760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2c770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2c780 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2c790 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2c7a0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
2c7b0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
2c7c0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
2c7d0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a uery Result.**.*
2c7e0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 * ^(The first pa
2c7f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
2c800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c810 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
2c820 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
2c830 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
2c840 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
2c850 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
2c860 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
2c870 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
2c880 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
2c890 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
2c8a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
2c8b0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
2c8c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
2c8d0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
2c8e0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
2c8f0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 .)^ ^If the Nth
2c900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
2c910 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
2c920 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
2c930 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
2c940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
2c950 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e s returned..** ^
2c960 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2c970 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
2c980 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a F-8 encoded..**.
2c990 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 ** ^(For example
2c9a0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
2c9b0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
2c9c0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
2c9d0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
2c9e0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
2ca00 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
2ca10 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
2ca20 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
2ca30 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
2ca40 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
2ca50 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
2ca60 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
2ca70 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
2ca80 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
2ca90 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
2caa0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
2cab0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
2cac0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e i==0).)^.**.** ^
2cad0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
2cae0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
2caf0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 ing. ^So just b
2cb00 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
2cb10 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
2cb20 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
2cb30 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
2cb40 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
2cb50 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
2cb60 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
2cb70 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
2cb80 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
2cb90 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
2cba0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
2cbb0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
2cbc0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e c not static. ^
2cbd0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 Type.** is assoc
2cbe0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 iated with indiv
2cbf0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f idual values, no
2cc00 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 t with the conta
2cc10 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f iners.** used to
2cc20 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 hold those valu
2cc30 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 es..*/.SQLITE_AP
2cc40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
2cc50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2cc60 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2cc70 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2cc80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2cc90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2cca0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 decltype16(sqlit
2ccb0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
2ccc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ccd0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 Evaluate An SQL
2cce0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
2ccf0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 After a [prepare
2cd00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 d statement] has
2cd10 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 been prepared u
2cd20 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b sing either.** [
2cd30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2cd40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
2cd50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2cd60 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 ] or one of the
2cd70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
2cd80 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 aces [sqlite3_pr
2cd90 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c epare()] or [sql
2cda0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2cdb0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ], this function
2cdc0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c .** must be call
2cdd0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
2cde0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 imes to evaluate
2cdf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a the statement..
2ce00 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
2ce10 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f s of the behavio
2ce20 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
2ce30 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 _step() interfac
2ce40 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 e depend.** on w
2ce50 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 hether the state
2ce60 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 ment was prepare
2ce70 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 d using the newe
2ce80 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 r "v2" interface
2ce90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2cea0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
2ceb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2cec0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6_v2()] or the o
2ced0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 lder legacy.** i
2cee0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 nterface [sqlite
2cef0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 3_prepare()] and
2cf00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2cf10 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 e16()]. The use
2cf20 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 of the.** new "
2cf30 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
2cf40 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
2cf50 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
2cf60 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 s but the legacy
2cf70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 .** interface wi
2cf80 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 ll continue to b
2cf90 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a e supported..**.
2cfa0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 ** ^In the legac
2cfb0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
2cfc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 return value wi
2cfd0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 ll be either [SQ
2cfe0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b LITE_BUSY],.** [
2cff0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 SQLITE_DONE], [S
2d000 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c QLITE_ROW], [SQL
2d010 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b ITE_ERROR], or [
2d020 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a SQLITE_MISUSE]..
2d030 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 ** ^With the "v2
2d040 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 " interface, any
2d050 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 of the other [r
2d060 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a esult codes] or.
2d070 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
2d080 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 ult codes] might
2d090 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 be returned as
2d0a0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 well..**.** ^[SQ
2d0b0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
2d0c0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
2d0d0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
2d0e0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
2d0f0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
2d100 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
2d110 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e o do its job. ^
2d120 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
2d130 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a is a [COMMIT].*
2d140 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 * or occurs outs
2d150 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 ide of an explic
2d160 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
2d170 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 then you can ret
2d180 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d ry the.** statem
2d190 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 ent. If the sta
2d1a0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 tement is not a
2d1b0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 [COMMIT] and occ
2d1c0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a urs within an.**
2d1d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2d1e0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 ction then you s
2d1f0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 hould rollback t
2d200 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 he transaction b
2d210 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 efore.** continu
2d220 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ing..**.** ^[SQL
2d230 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 ITE_DONE] means
2d240 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 that the stateme
2d250 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 nt has finished
2d260 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 executing.** suc
2d270 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 cessfully. sqli
2d280 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
2d290 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
2d2a0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 again on this vi
2d2b0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
2d2c0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 without first c
2d2d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2d2e0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 reset()] to rese
2d2f0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a t the virtual.**
2d300 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f machine back to
2d310 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
2d320 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 te..**.** ^If th
2d330 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2d340 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 being executed r
2d350 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c eturns any data,
2d360 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f then [SQLITE_RO
2d370 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 W].** is returne
2d380 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 d each time a ne
2d390 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 w row of data is
2d3a0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 ready for proce
2d3b0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 ssing by the.**
2d3c0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 caller. The valu
2d3d0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 es may be access
2d3e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f ed using the [co
2d3f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
2d400 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 tions]..** sqlit
2d410 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c e3_step() is cal
2d420 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 led again to ret
2d430 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 rieve the next r
2d440 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ow of data..**.*
2d450 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 * ^[SQLITE_ERROR
2d460 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 ] means that a r
2d470 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 un-time error (s
2d480 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 uch as a constra
2d490 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e int.** violation
2d4a0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 ) has occurred.
2d4b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2d4c0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2d4d0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a lled again on.**
2d4e0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e the VM. More in
2d4f0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 formation may be
2d500 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e found by callin
2d510 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 g [sqlite3_errms
2d520 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 g()]..** ^With t
2d530 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2d540 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
2d550 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
2d560 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (for example,.**
2d570 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
2d580 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 PT], [SQLITE_SCH
2d590 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EMA], [SQLITE_CO
2d5a0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 RRUPT], and so f
2d5b0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 orth).** can be
2d5c0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c obtained by call
2d5d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
2d5e0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 et()] on the.**
2d5f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d600 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 ent]. ^In the "
2d610 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a v2" interface,.*
2d620 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 * the more speci
2d630 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 fic error code i
2d640 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 s returned direc
2d650 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 tly by sqlite3_s
2d660 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 tep()..**.** [SQ
2d670 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 LITE_MISUSE] mea
2d680 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 ns that the this
2d690 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c routine was cal
2d6a0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 led inappropriat
2d6b0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 ely..** Perhaps
2d6c0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e it was called on
2d6d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d6e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
2d6f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e .** already been
2d700 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2d710 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 ze | finalized]
2d720 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 or on one that h
2d730 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 ad.** previously
2d740 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2d750 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c E_ERROR] or [SQL
2d760 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 ITE_DONE]. Or i
2d770 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 t could.** be th
2d780 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 e case that the
2d790 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
2d7a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e nnection is bein
2d7b0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 g used by two or
2d7c0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 .** more threads
2d7d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d at the same mom
2d7e0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a ent in time..**.
2d7f0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 ** For all versi
2d800 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 ons of SQLite up
2d810 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e to and includin
2d820 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 g 3.6.23.1, a ca
2d830 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2d840 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 3_reset()] was r
2d850 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 equired after sq
2d860 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 lite3_step() ret
2d870 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a urned anything.*
2d880 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 * other than [SQ
2d890 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 LITE_ROW] before
2d8a0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
2d8b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a invocation of.**
2d8c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
2d8d0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 Failure to res
2d8e0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 et the prepared
2d8f0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
2d900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2d910 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 et()] would resu
2d920 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 lt in an [SQLITE
2d930 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 _MISUSE] return
2d940 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
2d950 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 step(). But aft
2d960 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 er version 3.6.2
2d970 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 3.1, sqlite3_ste
2d980 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c p() began.** cal
2d990 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
2d9a0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 set()] automatic
2d9b0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 ally in this cir
2d9c0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 cumstance rather
2d9d0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 .** than returni
2d9e0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ng [SQLITE_MISUS
2d9f0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 E]. This is not
2da00 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f considered a co
2da10 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 mpatibility.** b
2da20 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 reak because any
2da30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 application tha
2da40 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 t ever receives
2da50 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 an SQLITE_MISUSE
2da60 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f error.** is bro
2da70 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f ken by definitio
2da80 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f n. The [SQLITE_
2da90 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 OMIT_AUTORESET]
2daa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2dab0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ion.** can be us
2dac0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 ed to restore th
2dad0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
2dae0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 r..**.** <b>Goof
2daf0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 y Interface Aler
2db00 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 t:</b> In the le
2db10 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2db20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
2db30 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 ().** API always
2db40 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
2db50 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b ic error code, [
2db60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 SQLITE_ERROR], f
2db70 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 ollowing any.**
2db80 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
2db90 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 [SQLITE_BUSY] a
2dba0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 nd [SQLITE_MISUS
2dbb0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 E]. You must ca
2dbc0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 ll.** [sqlite3_r
2dbd0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
2dbe0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2dbf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
2dc00 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 one of the.** s
2dc10 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2dc20 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 odes] that bette
2dc30 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 r describes the
2dc40 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d error..** We adm
2dc50 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 it that this is
2dc60 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 a goofy design.
2dc70 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 The problem has
2dc80 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 been fixed.** w
2dc90 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
2dca0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 erface. If you
2dcb0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 prepare all of y
2dcc0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e our SQL statemen
2dcd0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 ts.** using eith
2dce0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
2dcf0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
2dd00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2dd10 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a v2()] instead.**
2dd20 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b of the legacy [
2dd30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2dd40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2dd50 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 prepare16()] int
2dd60 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e erfaces,.** then
2dd70 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
2dd80 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
2dd90 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 are returned di
2dda0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c rectly.** by sql
2ddb0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 ite3_step(). Th
2ddc0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 e use of the "v2
2ddd0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
2dde0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 ecommended..*/.S
2ddf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2de00 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
2de10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2de20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2de30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2de40 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
2de50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2de60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 _data_count(P) i
2de70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2de80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2de90 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
2dea0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2deb0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
2dec0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
2ded0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 ement] P..** ^If
2dee0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2def0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 ent P does not h
2df00 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 ave results read
2df10 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 y to return.** (
2df20 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 via calls to the
2df30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2df40 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 _int | sqlite3_c
2df50 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a olumn_*()] of.**
2df60 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 interfaces) the
2df70 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 n sqlite3_data_c
2df80 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 ount(P) returns
2df90 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 0..** ^The sqlit
2dfa0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2dfb0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 routine also re
2dfc0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 turns 0 if P is
2dfd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
2dfe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2dff0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
2e000 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
2e010 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 if the previous
2e020 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2e030 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
2e040 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
2e050 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 NE]. ^The sqlit
2e060 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2e070 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
2e080 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 non-zero if prev
2e090 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ious call to [sq
2e0a0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
2e0b0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 eturned.** [SQLI
2e0c0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 TE_ROW], except
2e0d0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 in the case of t
2e0e0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 he [PRAGMA incre
2e0f0 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a mental_vacuum].*
2e100 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 * where it alway
2e110 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 s returns zero s
2e120 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f ince each step o
2e130 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 f that multi-ste
2e140 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 p.** pragma retu
2e150 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 rns 0 columns of
2e160 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 data..**.** See
2e170 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2e180 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a column_count()].
2e190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2e1a0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 t sqlite3_data_c
2e1b0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2e1c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2e1d0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 * CAPI3REF: Fund
2e1e0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 amental Datatype
2e1f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 s.** KEYWORDS: S
2e200 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a QLITE_TEXT.**.**
2e210 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 ^(Every value i
2e220 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 n SQLite has one
2e230 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 of five fundame
2e240 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a ntal datatypes:.
2e250 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
2e260 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 i> 64-bit signed
2e270 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e integer.** <li>
2e280 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 64-bit IEEE flo
2e290 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2e2a0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e er.** <li> strin
2e2b0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a g.** <li> BLOB.*
2e2c0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c * <li> NULL.** <
2e2d0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 /ul>)^.**.** The
2e2e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
2e2f0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
2e300 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
2e310 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2e320 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
2e330 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
2e340 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
2e350 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
2e360 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
2e370 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
2e380 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
2e390 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
2e3a0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
2e3b0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
2e3c0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
2e3d0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
2e3e0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
2e3f0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
2e400 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
2e410 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
2e420 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
2e430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e440 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
2e450 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
2e460 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
2e470 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
2e480 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
2e490 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
2e4a0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
2e4b0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
2e4c0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
2e4d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2e4e0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
2e4f0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 om A Query.** KE
2e500 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 YWORDS: {column
2e510 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
2e520 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
2e530 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 utines form the
2e540 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 "result set" int
2e550 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 erface..**.** ^T
2e560 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
2e570 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
2e580 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
2e590 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
2e5a0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
2e5b0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
2e5c0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 ^In every case
2e5d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
2e5e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a nt is a pointer.
2e5f0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 ** to the [prepa
2e600 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2e610 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 hat is being eva
2e620 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c luated (the [sql
2e630 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 ite3_stmt*].** t
2e640 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
2e650 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
2e660 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2e670 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
2e680 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 nts).** and the
2e690 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
2e6a0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
2e6b0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
2e6c0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
2e6d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
2e6e0 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 turned. ^The lef
2e6f0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 tmost column of
2e700 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 the result set h
2e710 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a as the index 0..
2e720 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f ** ^The number o
2e730 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2e740 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 result can be d
2e750 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a etermined using.
2e760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2e770 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a mn_count()]..**.
2e780 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
2e790 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
2e7a0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 currently point
2e7b0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c to a valid row,
2e7c0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f or if the.** co
2e7d0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 lumn index is ou
2e7e0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 t of range, the
2e7f0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
2e800 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ned..** These ro
2e810 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 utines may only
2e820 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 be called when t
2e830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2e840 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
2e850 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
2e860 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2e870 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 ROW] and neither
2e880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2e890 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 et()] nor [sqlit
2e8a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 e3_finalize()] h
2e8b0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
2e8c0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a subsequently..**
2e8d0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 If any of these
2e8e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
2e8f0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
2e900 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
2e910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2e920 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
2e930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2e940 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a ] has returned.*
2e950 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 * something othe
2e960 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
2e970 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 OW], the results
2e980 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
2e990 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 ** If [sqlite3_s
2e9a0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
2e9b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
2e9c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2e9d0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 ()].** are calle
2e9e0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 d from a differe
2e9f0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 nt thread while
2ea00 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
2ea10 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e tines.** are pen
2ea20 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ding, then the r
2ea30 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
2ea40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
2ea50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ea60 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 type() routine r
2ea70 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 eturns the.** [S
2ea80 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
2ea90 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
2eaa0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
2eab0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
2eac0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
2ead0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
2eae0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
2eaf0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2eb00 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
2eb10 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
2eb20 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
2eb30 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
2eb40 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
2eb50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
2eb60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2eb70 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
2eb80 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
2eb90 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
2eba0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
2ebb0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
2ebc0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
2ebd0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
2ebe0 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
2ebf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2ec00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
2ec10 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
2ec20 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
2ec30 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
2ec40 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
2ec50 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
2ec60 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
2ec70 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
2ec80 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
2ec90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2eca0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
2ecb0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 -8 string then t
2ecc0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2ecd0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 n_bytes().** rou
2ece0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
2ecf0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2ed00 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
2ed10 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2ed20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2ed30 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
2ed40 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2ed50 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
2ed60 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
2ed70 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
2ed80 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
2ed90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
2eda0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2edb0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
2edc0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
2edd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2ede0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
2edf0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
2ee00 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
2ee10 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 alue to a UTF-8
2ee20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
2ee30 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
2ee40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
2ee50 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
2ee60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
2ee70 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
2ee80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2ee90 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
2eea0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
2eeb0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
2eec0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 UTF-16 string t
2eed0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
2eee0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2eef0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
2ef00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2ef10 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
2ef20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
2ef30 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2ef40 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 t is a UTF-8 str
2ef50 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
2ef60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2ef70 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 () converts.** t
2ef80 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 he string to UTF
2ef90 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 -16 and then ret
2efa0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2efb0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
2efc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2efd0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
2efe0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2eff0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 mn_bytes16() use
2f000 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
2f010 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
2f020 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
2f030 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 to a UTF-16 stri
2f040 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
2f050 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
2f060 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
2f070 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
2f080 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
2f090 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2f0a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 lumn_bytes16() r
2f0b0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
2f0c0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 ** ^The values r
2f0d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
2f0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2f0f0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c ()] and .** [sql
2f100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2f110 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e s16()] do not in
2f120 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
2f130 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 erminators at th
2f140 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
2f150 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c string. ^For cl
2f160 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 arity: the value
2f170 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
2f180 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2f190 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 _bytes()] and [s
2f1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2f1b0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 tes16()] are the
2f1c0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 number of.** by
2f1d0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e tes in the strin
2f1e0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 g, not the numbe
2f1f0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
2f200 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 .**.** ^Strings
2f210 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2f220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2f230 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f ) and sqlite3_co
2f240 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a lumn_text16(),.*
2f250 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 * even empty str
2f260 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 ings, are always
2f270 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2f280 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a . ^The return.*
2f290 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
2f2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2f2b0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
2f2c0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e ngth BLOB is a N
2f2d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
2f2e0 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 ** ^The object r
2f2f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
2f300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
2f310 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e ()] is an.** [un
2f320 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2f330 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
2f340 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 An unprotected
2f350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2f360 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c bject.** may onl
2f370 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b y be used with [
2f380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
2f390 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
2f3a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
2f3b0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 )]..** If the [u
2f3c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2f3d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2f3e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2f3f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2f400 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 value()] is used
2f410 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 in any other wa
2f420 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c y, including cal
2f430 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 ls.** to routine
2f440 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
2f450 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 value_int()], [s
2f460 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2f470 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
2f480 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
2f490 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ()], then the be
2f4a0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
2f4b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
2f4c0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
2f4d0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
2f4e0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
2f4f0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a ropriate. ^For.
2f500 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
2f510 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
2f520 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
2f530 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
2f540 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
2f550 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
2f560 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
2f570 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
2f580 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
2f590 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
2f5a0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 matically. ^(Th
2f5b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
2f5c0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
2f5d0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
2f5e0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
2f5f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2f600 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
2f610 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
2f620 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
2f630 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
2f640 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
2f650 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
2f660 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
2f670 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
2f680 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
2f690 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
2f6a0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
2f6b0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
2f6c0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
2f6d0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
2f6e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2f6f0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 <td> Result is a
2f700 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
2f710 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
2f720 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2f730 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
2f740 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
2f750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
2f760 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 GER <td> FLOAT
2f770 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 <td> Convert
2f780 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f from integer to
2f790 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
2f7a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
2f7b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
2f7c0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
2f7d0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a of the integer.*
2f7e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2f7f0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 ER <td> BLOB
2f800 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 <td> Same as
2f810 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a INTEGER->TEXT.**
2f820 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2f830 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
2f840 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
2f850 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
2f860 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
2f870 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
2f880 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
2f890 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a g of the float.*
2f8a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
2f8b0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 T <td> BLOB
2f8c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
2f8d0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 o BLOB.** <tr><t
2f8e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2f8f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2f900 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
2f910 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 R.** <tr><td> T
2f920 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f EXT <td> FLO
2f930 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 AT <td> [CAST
2f940 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 ] to REAL.** <tr
2f950 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
2f960 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2f970 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
2f980 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
2f990 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2f9a0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
2f9b0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
2f9c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2f9d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2f9e0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a [CAST] to REAL.
2f9f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2fa00 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
2fa10 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
2fa20 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
2fa30 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
2fa40 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
2fa50 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 uote>)^.**.** Th
2fa60 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 e table above ma
2fa70 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f kes reference to
2fa80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
2fa90 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 ary functions at
2faa0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 oi().** and atof
2fab0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 (). SQLite does
2fac0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 not really use
2fad0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2fae0 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 It has its.**
2faf0 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 own equivalent i
2fb00 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 nternal routines
2fb10 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e . The atoi() an
2fb20 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 d atof() names a
2fb30 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 re.** used in th
2fb40 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 e table for brev
2fb50 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 ity and because
2fb60 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 they are familia
2fb70 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 r to most.** C p
2fb80 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a rogrammers..**.*
2fb90 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
2fba0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2fbb0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
2fbc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
2fbd0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
2fbe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2fbf0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
2fc00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
2fc10 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
2fc20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
2fc30 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
2fc40 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
2fc50 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
2fc60 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
2fc70 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
2fc80 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
2fc90 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
2fca0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
2fcb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2fcc0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
2fcd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2fce0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
2fcf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2fd00 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
2fd10 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
2fd20 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
2fd30 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
2fd40 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
2fd50 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
2fd60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2fd70 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
2fd80 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
2fd90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
2fda0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
2fdb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2fdc0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
2fdd0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
2fde0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
2fdf0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
2fe00 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
2fe10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2fe20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
2fe30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2fe40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
2fe50 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
2fe60 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
2fe70 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
2fe80 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
2fe90 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
2fea0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
2feb0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
2fec0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
2fed0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
2fee0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
2fef0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
2ff00 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
2ff10 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
2ff20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
2ff30 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
2ff40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
2ff50 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
2ff60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
2ff70 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
2ff80 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
2ff90 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
2ffa0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
2ffb0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
2ffc0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
2ffd0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
2ffe0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
2fff0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
30000 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
30010 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
30020 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
30030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
30040 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
30050 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
30060 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
30070 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
30080 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
30090 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
300a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
300b0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
300c0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
300d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
300e0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
300f0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
30100 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
30110 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
30120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
30130 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
30140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30150 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
30160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30170 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
30180 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
30190 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
301a0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
301b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
301c0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
301d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
301e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
301f0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
30200 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
30210 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
30220 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
30230 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
30240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30250 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
30260 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
30270 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
30280 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
30290 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
302a0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
302b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
302c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
302d0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
302e0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
302f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
30300 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
30310 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
30320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
30330 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
30340 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
30350 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
30360 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 ** ^The pointers
30370 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
30380 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
30390 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
303a0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
303b0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
303c0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
303d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
303e0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
303f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
30400 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
30410 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 ^The memory spac
30420 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 e used to hold s
30430 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c trings.** and BL
30440 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 OBs is freed aut
30450 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 omatically. Do
30460 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 <b>not</b> pass
30470 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 the pointers ret
30480 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
30490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
304a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
304b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 column_text()],
304c0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 etc. into.** [sq
304d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
304e0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f *.** ^(If a memo
304f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
30500 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
30510 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e g the evaluation
30520 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
30530 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 ese routines, a
30540 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 default value is
30550 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
30560 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a default value.**
30570 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 is either the i
30580 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c nteger 0, the fl
30590 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
305a0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 ber 0.0, or a NU
305b0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 LL.** pointer.
305c0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 Subsequent calls
305d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
305e0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 code()] will ret
305f0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e urn.** [SQLITE_N
30600 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 OMEM].)^.*/.SQLI
30610 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
30620 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
30630 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
30640 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30650 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
30660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30670 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
30680 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
30690 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
306a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
306b0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
306c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
306d0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
306e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
306f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
30700 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30710 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
30720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
30730 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
30740 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
30750 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
30760 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
30770 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
30780 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
30790 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
307a0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
307b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
307c0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
307d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
307e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
307f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
30800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
30810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
30820 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
30830 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
30840 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c _column_type(sql
30850 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
30860 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
30870 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 I sqlite3_value
30880 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
30890 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
308a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
308b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
308c0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
308d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
308e0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ject.**.** ^The
308f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
30900 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
30910 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 alled to delete
30920 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
30930 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 ement]..** ^If t
30940 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
30950 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 valuation of the
30960 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 statement encou
30970 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 ntered no errors
30980 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 .** or if the st
30990 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 atement is never
309a0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c been evaluated,
309b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 then sqlite3_fi
309c0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 nalize() returns
309d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 .** SQLITE_OK.
309e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
309f0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f ent evaluation o
30a00 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 f statement S fa
30a10 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 iled, then.** sq
30a20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
30a30 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 ) returns the ap
30a40 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
30a50 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 code] or.** [ex
30a60 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
30a70 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 e]..**.** ^The s
30a80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
30a90 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 S) routine can b
30aa0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
30ab0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 point during.**
30ac0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f the life cycle o
30ad0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
30ae0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 ement] S:.** bef
30af0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 ore statement S
30b00 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 is ever evaluate
30b10 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 d, after.** one
30b20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f or more calls to
30b30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
30b40 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 )], or after any
30b50 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c call.** to [sql
30b60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 ite3_step()] reg
30b70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
30b80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 er or not the st
30b90 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 atement has.** c
30ba0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
30bb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b on..**.** ^Invok
30bc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 ing sqlite3_fina
30bd0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c lize() on a NULL
30be0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 pointer is a ha
30bf0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a rmless no-op..**
30c00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
30c10 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a ion must finaliz
30c20 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 e every [prepare
30c30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
30c40 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a order to avoid.*
30c50 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 * resource leaks
30c60 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 . It is a griev
30c70 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 ous error for th
30c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f e application to
30c90 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 try to use.** a
30ca0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
30cb0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
30cc0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e been finalized.
30cd0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 Any use of a p
30ce0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
30cf0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
30d00 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
30d10 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 can result in u
30d20 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 ndefined and.**
30d30 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
30d40 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 vior such as seg
30d50 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 faults and heap
30d60 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 corruption..*/.S
30d70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
30d80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 lite3_finalize(s
30d90 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
30da0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
30db0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 3REF: Reset A Pr
30dc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
30dd0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
30de0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
30df0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
30e00 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
30e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
30e20 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
30e30 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
30e40 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
30e50 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
30e60 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 d..** ^Any SQL s
30e70 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c tatement variabl
30e80 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 es that had valu
30e90 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d es bound to them
30ea0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 using.** the [s
30eb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
30ec0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f | sqlite3_bind_
30ed0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 *() API] retain
30ee0 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a their values..**
30ef0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c Use [sqlite3_cl
30f00 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 ear_bindings()]
30f10 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e to reset the bin
30f20 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 dings..**.** ^Th
30f30 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
30f40 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
30f50 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 esets the [prepa
30f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
30f70 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 .** back to the
30f80 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
30f90 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
30fa0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
30fb0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
30fc0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
30fd0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
30fe0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
30ff0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
31000 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _ROW] or [SQLITE
31010 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 _DONE],.** or if
31020 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
31030 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 )] has never bef
31040 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ore been called
31050 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 on S,.** then [s
31060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
31070 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
31080 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 _OK]..**.** ^If
31090 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
310a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
310b0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
310c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
310d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 tatement] S indi
310e0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 cated an error,
310f0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 then.** [sqlite3
31100 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
31110 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
31120 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
31130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
31140 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
31150 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
31160 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
31170 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 es.** of any [sq
31180 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
31190 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 bindings] on the
311a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
311b0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 ment] S..*/.SQLI
311c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
311d0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
311e0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
311f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31200 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
31210 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
31220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
31230 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
31240 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
31250 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
31260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
31270 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
31280 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
31290 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
312a0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a functions}.**.*
312b0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
312c0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 ns (collectively
312d0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 known as "funct
312e0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
312f0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 tines").** are u
31300 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 sed to add SQL f
31310 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
31320 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 egates or to red
31330 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 efine the behavi
31340 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e or.** of existin
31350 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 g SQL functions
31360 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 or aggregates.
31370 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 The only differe
31380 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 nces between.**
31390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
313a0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f re the text enco
313b0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f ding expected fo
313c0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 r.** the second
313d0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e parameter (the n
313e0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 ame of the funct
313f0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 ion being create
31400 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 d).** and the pr
31410 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 esence or absenc
31420 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f e of a destructo
31430 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a r callback for.*
31440 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
31450 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a n data pointer..
31460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
31470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
31480 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
31490 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
314a0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
314b0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
314c0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 ded. ^If an app
314d0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f lication uses mo
314e0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 re than one data
314f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
31500 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 on then applicat
31510 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
31520 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
31530 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 e added.** to ea
31540 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
31550 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c ection separatel
31560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 y..**.** ^The se
31570 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
31580 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
31590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
315a0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a o be created or.
315b0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e ** redefined. ^
315c0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
315d0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
315e0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 d to 255 bytes i
315f0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 n a UTF-8.** rep
31600 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 resentation, exc
31610 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 lusive of the ze
31620 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro-terminator.
31630 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e ^Note that the n
31640 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 ame.** length li
31650 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 mit is in UTF-8
31660 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 bytes, not chara
31670 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 cters nor UTF-16
31680 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e bytes. .** ^An
31690 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 y attempt to cre
316a0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 ate a function w
316b0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d ith a longer nam
316c0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 e.** will result
316d0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 in [SQLITE_MISU
316e0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e SE] being return
316f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 ed..**.** ^The t
31700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 hird parameter (
31710 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 nArg).** is the
31720 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
31730 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c nts that the SQL
31740 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
31750 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e aggregate takes.
31760 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 ^If this parame
31770 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 ter is -1, then
31780 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
31790 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
317a0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
317b0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
317c0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 s between 0 and
317d0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 the limit.** set
317e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
317f0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
31800 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 T_FUNCTION_ARG])
31810 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a . If the third.
31820 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ** parameter is
31830 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 less than -1 or
31840 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 greater than 127
31850 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
31860 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e or is.** undefin
31870 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
31880 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c ourth parameter,
31890 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 eTextRep, speci
318a0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 fies what.** [SQ
318b0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 LITE_UTF8 | text
318c0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 encoding] this
318d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 SQL function pre
318e0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 fers for.** its
318f0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 parameters. The
31900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
31910 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 uld set this par
31920 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 ameter to.** [SQ
31930 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 LITE_UTF16LE] if
31940 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d the function im
31950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 plementation inv
31960 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 okes .** [sqlite
31970 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
31980 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c ()] on an input,
31990 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
319a0 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6BE] if the.** i
319b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
319c0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 vokes [sqlite3_v
319d0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d alue_text16be()]
319e0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 on an input, or
319f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
31a00 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 6] if [sqlite3_v
31a10 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 alue_text16()] i
31a20 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 s used, or [SQLI
31a30 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 TE_UTF8].** othe
31a40 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d rwise. ^The sam
31a50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d e SQL function m
31a60 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 ay be registered
31a70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
31a80 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 using.** differe
31a90 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 nt preferred tex
31aa0 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 t encodings, wit
31ab0 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c h different impl
31ac0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a ementations for.
31ad0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 ** each encoding
31ae0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 ..** ^When multi
31af0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
31b00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
31b10 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 function are ava
31b20 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a ilable, SQLite.*
31b30 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 * will pick the
31b40 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 one that involve
31b50 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
31b60 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 nt of data conve
31b70 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rsion..**.** ^Th
31b80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
31b90 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c er may optionall
31ba0 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b y be ORed with [
31bb0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 SQLITE_DETERMINI
31bc0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e STIC].** to sign
31bd0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 al that the func
31be0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 tion will always
31bf0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 return the same
31c00 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a result given.**
31c10 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 the same inputs
31c20 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 within a single
31c30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
31c40 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 Most SQL functi
31c50 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 ons are.** deter
31c60 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 ministic. The b
31c70 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 uilt-in [random(
31c80 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 )] SQL function
31c90 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 is an example of
31ca0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 a.** function t
31cb0 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 hat is not deter
31cc0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 ministic. The S
31cd0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e QLite query plan
31ce0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a ner is able to.*
31cf0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 * perform additi
31d00 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f onal optimizatio
31d10 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 ns on determinis
31d20 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 tic functions, s
31d30 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 o use.** of the
31d40 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e [SQLITE_DETERMIN
31d50 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 ISTIC] flag is r
31d60 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 ecommended where
31d70 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a possible..**.**
31d80 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 ^(The fifth par
31d90 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 ameter is an arb
31da0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 itrary pointer.
31db0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
31dc0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 ion of the.** fu
31dd0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 nction can gain
31de0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 access to this p
31df0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 ointer using [sq
31e00 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
31e10 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 )].)^.**.** ^The
31e20 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 sixth, seventh
31e30 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d and eighth param
31e40 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
31e50 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
31e60 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
31e70 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
31e80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
31e90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
31ea0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
31eb0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c gregate. ^A scal
31ec0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
31ed0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
31ee0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
31ef0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
31f00 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 ack only; NULL p
31f10 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 ointers must be
31f20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 passed as the xS
31f30 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a tep and xFinal.*
31f40 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 * parameters. ^A
31f50 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
31f60 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
31f70 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
31f80 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 ion of xStep.**
31f90 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
31fa0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 ULL pointer must
31fb0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
31fc0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 Func. ^To delete
31fd0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 an existing.**
31fe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 SQL function or
31ff0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 aggregate, pass
32000 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f NULL pointers fo
32010 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
32020 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
32030 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 s..**.** ^(If th
32040 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 e ninth paramete
32050 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
32060 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
32070 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a ) is not NULL,.*
32080 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 * then it is des
32090 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 tructor for the
320a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
320b0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 pointer. .** Th
320c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
320d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 invoked when the
320e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c function is del
320f0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 eted, either by
32100 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 being.** overloa
32110 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 ded or when the
32120 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32130 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a ion closes.)^.**
32140 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
32150 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 is also invoked
32160 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a if the call to.
32170 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ** sqlite3_creat
32180 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
32190 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 fails..** ^When
321a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 the destructor c
321b0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 allback of the t
321c0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 enth parameter i
321d0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a s invoked, it.**
321e0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e is passed a sin
321f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
32200 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ch is a copy of
32210 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32220 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 data .** pointer
32230 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 which was the f
32240 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 ifth parameter t
32250 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
32260 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a _function_v2()..
32270 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 **.** ^It is per
32280 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 mitted to regist
32290 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c er multiple impl
322a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
322b0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 he same.** funct
322c0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 ions with the sa
322d0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 me name but with
322e0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e either differin
322f0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 g numbers of.**
32300 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 arguments or dif
32310 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 fering preferred
32320 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e text encodings.
32330 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 ^SQLite will u
32340 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
32350 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f entation that mo
32360 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 st closely match
32370 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 es the way in wh
32380 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 ich the.** SQL f
32390 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e unction is used.
323a0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d ^A function im
323b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
323c0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 h a non-negative
323d0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 .** nArg paramet
323e0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d er is a better m
323f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
32400 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
32410 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 ion with.** a ne
32420 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 gative nArg. ^A
32430 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
32440 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 the preferred te
32450 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d xt encoding.** m
32460 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 atches the datab
32470 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ase encoding is
32480 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 a better.** matc
32490 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
324a0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
324b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
324c0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 t. .** ^A funct
324d0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
324e0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
324f0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 e is between UTF
32500 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 16le and UTF16be
32510 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 .** is a closer
32520 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
32530 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
32540 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
32550 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 nce is.** betwee
32560 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 n UTF8 and UTF16
32570 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 ..**.** ^Built-i
32580 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 n functions may
32590 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 be overloaded by
325a0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
325b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
325c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 ns..**.** ^An ap
325d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
325e0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 d function is pe
325f0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 rmitted to call
32600 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
32610 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 interfaces. How
32620 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 ever, such calls
32630 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f must not.** clo
32640 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
32650 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 connection nor f
32660 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 inalize or reset
32670 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a the prepared.**
32680 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 statement in wh
32690 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ich the function
326a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
326b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
326c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
326d0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
326e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
326f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
32700 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
32710 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
32720 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
32730 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
32740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
32750 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
32760 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
32770 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
32780 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
32790 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
327a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
327b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
327c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
327d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
327e0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 function16(. sq
327f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
32800 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 st void *zFuncti
32810 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
32820 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
32830 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
32840 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
32850 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
32860 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
32870 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
32880 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
32890 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
328a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
328b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
328c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
328d0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
328e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
328f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
32900 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
32910 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
32920 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
32930 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
32940 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
32950 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
32960 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
32970 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
32980 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
32990 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
329a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
329b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
329c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
329d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
329e0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 ntext*),. void(
329f0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
32a00 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
32a10 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
32a20 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ings.**.** These
32a30 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
32a40 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
32a50 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
32a60 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
32a70 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
32a80 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
32a90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
32aa0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
32ab0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
32ac0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
32ad0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
32ae0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
32af0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
32b00 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
32b10 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
32b20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
32b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
32b40 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
32b50 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 5 /* Depreca
32b60 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ted */.#define S
32b70 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
32b80 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c NED 8 /* sql
32b90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
32ba0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f ation only */../
32bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
32bc0 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a unction Flags.**
32bd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
32be0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 nts may be ORed
32bf0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 together with th
32c00 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 e .** [SQLITE_UT
32c10 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 F8 | preferred t
32c20 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 ext encoding] as
32c30 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
32c40 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ment.** to [sqli
32c50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
32c60 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
32c70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32c80 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
32c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
32ca0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a ction_v2()]..*/.
32cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
32cc0 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 ETERMINISTIC
32cd0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 0x800../*.** CAP
32ce0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
32cf0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 d Functions.** D
32d00 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
32d10 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
32d20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d are [deprecated]
32d30 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d . In order to m
32d40 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 aintain.** backw
32d50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
32d60 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f ty with older co
32d70 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 de, these functi
32d80 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a ons continue .**
32d90 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
32da0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 . However, new
32db0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f applications sho
32dc0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 uld avoid.** the
32dd0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 use of these fu
32de0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c nctions. To hel
32df0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 p encourage peop
32e00 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 le to avoid.** u
32e10 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 sing these funct
32e20 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 ions, we are not
32e30 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 going to tell y
32e40 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e ou what they do.
32e50 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
32e60 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 TE_OMIT_DEPRECAT
32e70 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 ED.SQLITE_API SQ
32e80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
32e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 int sqlite3_aggr
32ea0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 egate_count(sqli
32eb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
32ec0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
32ed0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
32ee0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 sqlite3_expired(
32ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
32f00 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
32f10 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
32f20 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
32f30 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
32f40 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
32f50 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
32f60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
32f70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
32f80 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
32f90 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f r(void);.SQLITE_
32fa0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
32fb0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
32fc0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
32fd0 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
32fe0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
32ff0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
33000 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
33010 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
33020 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
33030 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
33040 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
33050 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
33060 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
33070 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
33080 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 QL Function Para
33090 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a meter Values.**.
330a0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
330b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
330c0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
330d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
330e0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
330f0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
33100 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
33110 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
33120 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
33130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
33140 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 regate..**.** Th
33150 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
33160 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
33170 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
33180 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
33190 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
331a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
331b0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
331c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
331d0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
331e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
331f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
33200 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
33210 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
33220 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
33230 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
33240 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
33250 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
33260 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
33270 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
33280 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
33290 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
332a0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
332b0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
332c0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
332d0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
332e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
332f0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
33300 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
33310 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
33320 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
33330 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
33340 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
33350 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
33360 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
33370 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
33380 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
33390 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
333a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
333b0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
333c0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
333d0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
333e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
333f0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
33400 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
33410 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
33420 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
33430 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 except that th
33440 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
33450 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
33460 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33470 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
33480 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
33490 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
334a0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
334b0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
334c0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
334d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
334e0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
334f0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
33500 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
33510 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
33520 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
33530 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
33540 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
33550 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
33560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
33570 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
33580 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
33590 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
335a0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
335b0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
335c0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
335d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
335e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
335f0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
33600 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
33610 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
33620 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
33630 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
33640 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
33650 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
33660 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
33670 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
33680 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
33690 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
336a0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
336b0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
336c0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
336d0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
336e0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
336f0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
33700 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
33710 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
33720 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
33730 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
33740 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
33750 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
33760 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
33770 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
33780 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
33790 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
337a0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
337b0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
337c0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
337d0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
337e0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
337f0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
33800 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
33810 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
33820 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
33830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
33840 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
33850 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
33860 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
33870 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
33880 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
33890 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
338a0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
338b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
338c0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
338d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
338e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
338f0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
33900 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
33910 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
33920 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
33930 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
33940 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
33950 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
33960 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
33970 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
33980 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
33990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
339a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
339b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
339c0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
339d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
339e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
339f0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
33a00 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
33a10 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c E_API double sql
33a20 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
33a30 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
33a40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
33a50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
33a60 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
33a70 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
33a80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
33a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
33aa0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 4(sqlite3_value*
33ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
33ac0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
33ad0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
33ae0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
33af0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
33b00 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
33b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
33b20 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
33b30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
33b40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
33b50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
33b60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
33b70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
33b80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
33b90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
33ba0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
33bb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
33bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
33bd0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
33be0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
33bf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
33c00 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
33c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
33c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33c30 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
33c40 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
33c50 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
33c60 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
33c70 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
33c80 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
33c90 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
33ca0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
33cb0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
33cc0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
33cd0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
33ce0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
33cf0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
33d00 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
33d10 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
33d20 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
33d30 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
33d40 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
33d50 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
33d60 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
33d70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
33d80 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
33d90 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
33da0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
33db0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
33dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
33dd0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
33de0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
33df0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
33e00 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
33e10 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
33e20 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
33e30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
33e40 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
33e50 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
33e60 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
33e70 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
33e80 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
33e90 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
33ea0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
33eb0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
33ec0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
33ed0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
33ee0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
33ef0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
33f00 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
33f10 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
33f20 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
33f30 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
33f40 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
33f50 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
33f60 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
33f70 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
33f80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
33f90 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
33fa0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
33fb0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
33fc0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
33fd0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
33fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
33ff0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
34000 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
34010 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
34020 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 er .** when firs
34030 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 t called if N is
34040 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
34050 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 ual to zero or i
34060 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c f a memory.** al
34070 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
34080 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
34090 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
340a0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
340b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
340c0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
340d0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
340e0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
340f0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
34100 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
34110 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
34120 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
34130 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
34140 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34150 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
34160 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
34170 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
34180 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
34190 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
341a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
341b0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 .)^ Within the
341c0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c xFinal callback,
341d0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 it is customary
341e0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 to set.** N=0 i
341f0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
34200 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
34210 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 text(C,N) so tha
34220 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 t no .** pointle
34230 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ss memory alloca
34240 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a tions occur..**.
34250 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
34260 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
34270 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
34280 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
34290 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
342a0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
342b0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
342c0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
342d0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
342e0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
342f0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
34300 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
34310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
34320 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
34330 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
34340 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
34350 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
34360 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
34370 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
34380 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
34390 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
343a0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
343b0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
343c0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
343d0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
343e0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
343f0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
34400 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
34410 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 void *sqlite3_a
34420 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
34430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34440 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
34450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34460 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
34470 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
34480 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 The sqlite3_user
34490 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 _data() interfac
344a0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
344b0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
344c0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
344d0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 pUserData parame
344e0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 ter (the 5th par
344f0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
34500 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
34510 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
34520 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
34530 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
34540 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
34550 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
34560 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
34570 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
34580 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
34590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
345a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
345b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
345c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
345d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
345e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
345f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
34600 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
34610 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
34620 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
34630 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
34640 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
34650 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
34660 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 nctions.**.** ^T
34670 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 he sqlite3_conte
34680 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 xt_db_handle() i
34690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
346a0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
346b0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
346c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
346d0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 ction] (the 1st
346e0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
346f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
34700 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
34710 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
34720 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
34730 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
34740 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
34750 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
34760 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
34770 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
34780 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
34790 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
347a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
347b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
347c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
347d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
347e0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a iliary Data.**.*
347f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
34800 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
34810 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 (non-aggregate)
34820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
34830 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
34840 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
34850 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
34860 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
34870 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
34880 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
34890 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
348a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
348b0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
348c0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
348d0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
348e0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
348f0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
34900 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 preserved. An
34910 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 example.** of wh
34920 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 ere this might b
34930 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 e useful is in a
34940 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
34950 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 ion matching.**
34960 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
34970 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
34980 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
34990 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
349a0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
349b0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
349c0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 with the patter
349d0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 n string. .** T
349e0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 hen as long as t
349f0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e he pattern strin
34a00 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 g remains the sa
34a10 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 me,.** the compi
34a20 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 led regular expr
34a30 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 ession can be re
34a40 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 used on multiple
34a50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
34a60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
34a70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
34a80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
34a90 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
34aa0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
34ab0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
34ac0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
34ad0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
34ae0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
34af0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
34b00 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
34b10 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
34b20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34b30 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 function. ^If t
34b40 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 here is no metad
34b50 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
34b60 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 d with the funct
34b70 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 ion argument, th
34b80 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 is sqlite3_get_a
34b90 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
34ba0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ce.** returns a
34bb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
34bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34bd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
34be0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 ,P,X) interface
34bf0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 saves P as metad
34c00 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
34c10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
34c20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34c30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34c40 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a . ^Subsequent.*
34c50 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
34c60 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 e3_get_auxdata(C
34c70 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f ,N) return P fro
34c80 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e m the most recen
34c90 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 t.** sqlite3_set
34ca0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
34cb0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 ) call if the me
34cc0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 tadata is still
34cd0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c valid or.** NULL
34ce0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 if the metadata
34cf0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 has been discar
34d00 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 ded..** ^After e
34d10 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
34d20 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
34d30 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 C,N,P,X) where X
34d40 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a is not NULL,.**
34d50 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
34d60 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
34d70 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 or function X wi
34d80 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 th parameter P e
34d90 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 xactly.** once,
34da0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 when the metadat
34db0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a a is discarded..
34dc0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
34dd0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 e to discard the
34de0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 metadata at any
34df0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 time, including
34e00 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 : <ul>.** <li> w
34e10 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
34e20 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 nding function p
34e30 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 arameter changes
34e40 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 , or.** <li> whe
34e50 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
34e60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
34e70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
34e80 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a alled for the.**
34e90 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d SQL statem
34ea0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ent, or.** <li>
34eb0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 when sqlite3_set
34ec0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e _auxdata() is in
34ed0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 voked again on t
34ee0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 he same paramete
34ef0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 r, or.** <li> du
34f00 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
34f10 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 l sqlite3_set_au
34f20 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 xdata() call whe
34f30 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 n a memory .**
34f40 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 allocation e
34f50 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 rror occurs. </u
34f60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 l>)^.**.** Note
34f70 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 the last bullet
34f80 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 in particular.
34f90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 The destructor X
34fa0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f in .** sqlite3_
34fb0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
34fc0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 P,X) might be ca
34fd0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 lled immediately
34fe0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 , before the.**
34ff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
35000 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
35010 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 even returns. H
35020 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ence sqlite3_set
35030 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 _auxdata().** sh
35040 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e ould be called n
35050 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ear the end of t
35060 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
35070 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 ementation and t
35080 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 he.** function i
35090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
350a0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e ould not make an
350b0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 y use of P after
350c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
350d0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 auxdata() has be
350e0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a en called..**.**
350f0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ^(In practice,
35100 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 metadata is pres
35110 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 erved between fu
35120 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 nction calls for
35130 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
35140 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
35150 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f compile-time co
35160 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 nstants, includi
35170 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 ng literal.** va
35180 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 lues and [parame
35190 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 ters] and expres
351a0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 sions composed f
351b0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a rom the same.)^.
351c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
351d0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
351e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
351f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
35200 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
35210 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
35220 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
35230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
35240 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
35250 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
35260 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 N);.SQLITE_API v
35270 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f oid sqlite3_set_
35280 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
35290 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c context*, int N,
352a0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 void*, void (*)
352b0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a (void*));.../*.*
352c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 * CAPI3REF: Cons
352d0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 tants Defining S
352e0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f pecial Destructo
352f0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a r Behavior.**.**
35300 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
35310 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
35320 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
35330 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
35340 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
35350 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
35360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
35370 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
35380 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 . ^If the destr
35390 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e uctor.** argumen
353a0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 t is SQLITE_STAT
353b0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 IC, it means tha
353c0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f t the content po
353d0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e inter is constan
353e0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 t.** and will ne
353f0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 ver change. It
35400 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
35410 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 be destroyed.
35420 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 ^The.** SQLITE_T
35430 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d RANSIENT value m
35440 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
35450 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c ntent will likel
35460 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 y change in.** t
35470 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 he near future a
35480 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 nd that SQLite s
35490 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f hould make its o
354a0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
354b0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e of.** the conten
354c0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 t before returni
354d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 ng..**.** The ty
354e0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 pedef is necessa
354f0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e ry to work aroun
35500 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 d problems in ce
35510 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d rtain.** C++ com
35520 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 pilers..*/.typed
35530 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
35540 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
35550 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
35560 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
35570 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
35580 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
35590 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
355a0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
355b0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
355c0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
355d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
355e0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
355f0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
35600 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
35610 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
35620 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
35630 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
35640 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
35650 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
35660 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
35670 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
35680 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35690 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
356a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
356b0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
356c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
356d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
356e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
356f0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
35700 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 the [parameter
35710 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 binding] family
35720 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 of.** functions
35730 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c used to bind val
35740 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 ues to host para
35750 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 meters in prepar
35760 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a ed statements..*
35770 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b * Refer to the [
35780 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 SQL parameter] d
35790 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
357a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
357b0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e rmation..**.** ^
357c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
357d0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 lt_blob() interf
357e0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
357f0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
35800 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
35810 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
35820 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 e the BLOB whose
35830 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e content is poin
35840 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 ted.** to by the
35850 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
35860 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e r and which is N
35870 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 bytes long wher
35880 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 e N is the.** th
35890 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ird parameter..*
358a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
358b0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
358c0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
358d0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
358e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
358f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
35900 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
35910 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
35920 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
35930 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
35940 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
35950 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
35960 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
35970 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35980 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
35990 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
359a0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
359b0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
359c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
359d0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
359e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
359f0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
35a00 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
35a10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
35a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35a30 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
35a40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
35a50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
35a60 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
35a70 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
35a80 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
35a90 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c ception..** ^SQL
35aa0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 ite uses the str
35ab0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ing pointed to b
35ac0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 y the.** 2nd par
35ad0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
35ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
35af0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
35b00 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
35b10 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 as the text of a
35b20 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
35b30 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 ^SQLite interp
35b40 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
35b50 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
35b60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
35b70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
35b80 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a UTF-8. ^SQLite.*
35b90 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
35ba0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
35bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35bc0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
35bd0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
35be0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 e order. ^If th
35bf0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
35c00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
35c10 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
35c20 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
35c30 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
35c40 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
35c50 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
35c60 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
35c70 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
35c80 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
35c90 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
35ca0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
35cb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
35cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35cd0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
35ce0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
35cf0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
35d00 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
35d10 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
35d20 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
35d30 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
35d40 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
35d50 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
35d60 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 sage..** ^The sq
35d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35d80 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
35d90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
35da0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
35db0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
35dc0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
35dd0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
35de0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
35df0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
35e00 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
35e10 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
35e20 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
35e30 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
35e40 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
35e50 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c arm..** ^The sql
35e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35e70 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f r_code() functio
35e80 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 n changes the er
35e90 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 ror code.** retu
35ea0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 rned by SQLite a
35eb0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e s a result of an
35ec0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 error in a func
35ed0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 tion. ^By defau
35ee0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
35ef0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
35f00 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 ERROR. ^A subse
35f10 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
35f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35f30 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
35f40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
35f50 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
35f60 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
35f70 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
35f80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
35f90 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
35fa0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
35fb0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
35fc0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
35fd0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
35fe0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f a string or BLO
35ff0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f B is too long to
36000 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a represent..**.*
36010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
36020 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
36030 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
36040 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
36050 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
36060 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
36070 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
36080 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
36090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
360a0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 result_int() int
360b0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
360c0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
360d0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
360e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
360f0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 ion to be the 32
36100 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
36110 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
36120 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
36130 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
36140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
36150 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 nt64() interface
36160 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
36170 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
36180 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
36190 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
361a0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 be the 64-bit s
361b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
361c0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
361d0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
361e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
361f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
36200 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
36210 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
36220 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
36230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36240 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36250 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
36260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36270 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f text(), sqlite3_
36280 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c result_text16(),
36290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
362a0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 lt_text16le(), a
362b0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
362c0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 t_text16be() int
362d0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 erfaces.** set t
362e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
362f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
36300 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36310 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 ion to be.** a t
36320 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 ext string which
36330 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
36340 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 as UTF-8, UTF-16
36350 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
36360 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 er,.** UTF-16 li
36370 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 ttle endian, or
36380 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 UTF-16 big endia
36390 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
363a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 .** ^SQLite take
363b0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c s the text resul
363c0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 t from the appli
363d0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 cation from.** t
363e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
363f0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
36400 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
36410 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 erfaces..** ^If
36420 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
36430 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
36440 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
36450 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
36460 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 egative, then SQ
36470 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c Lite takes resul
36480 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 t text from the
36490 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 2nd parameter.**
364a0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
364b0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
364c0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 r..** ^If the 3r
364d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
364e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
364f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
36500 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 es.** is non-neg
36510 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d ative, then as m
36520 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 any bytes (not c
36530 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 haracters) of th
36540 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 e text.** pointe
36550 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 d to by the 2nd
36560 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 parameter are ta
36570 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 ken as the appli
36580 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a cation-defined.*
36590 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c * function resul
365a0 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 t. If the 3rd p
365b0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d arameter is non-
365c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 negative, then i
365d0 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 t.** must be the
365e0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 byte offset int
365f0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 o the string whe
36600 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 re the NUL termi
36610 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 nator would.** a
36620 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 ppear if the str
36630 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 ing where NUL te
36640 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
36650 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
36660 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
36670 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 string at a byt
36680 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 e offset that is
36690 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 less than the v
366a0 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a alue of the 3rd.
366b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 ** parameter, th
366c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 en the resulting
366d0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e string will con
366e0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
366f0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 Ls and the.** re
36700 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
36710 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e ons operating on
36720 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d strings with em
36730 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
36740 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 ndefined..** ^If
36750 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
36760 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
36770 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
36780 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
36790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
367a0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c lob is a non-NUL
367b0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
367c0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 SQLite calls tha
367d0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 t.** function as
367e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
367f0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 on the text or B
36800 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 LOB result when
36810 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 it has.** finish
36820 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
36830 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 sult..** ^If the
36840 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
36850 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
36860 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
36870 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 faces or to.** s
36880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
36890 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
368a0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
368b0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 E_STATIC, then S
368c0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 QLite.** assumes
368d0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f that the text o
368e0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 r BLOB result is
368f0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 in constant spa
36900 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a ce and does not.
36910 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 ** copy the cont
36920 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d ent of the param
36930 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 eter nor call a
36940 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
36950 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 e content.** whe
36960 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
36970 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
36980 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ult..** ^If the
36990 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
369a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
369b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
369c0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
369d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
369e0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
369f0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 nstant SQLITE_TR
36a00 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 ANSIENT.** then
36a10 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
36a20 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c opy of the resul
36a30 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 t into space obt
36a40 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 ained from.** fr
36a50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
36a60 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 oc()] before it
36a70 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
36a80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36a90 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
36aa0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
36ab0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
36ac0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36ad0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
36ae0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 e a copy the.**
36af0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
36b00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
36b10 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ct specified by
36b20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
36b30 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 r. ^The.** sqli
36b40 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
36b50 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b () interface mak
36b60 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
36b70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
36b80 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 .** so that the
36b90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
36ba0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 specified in the
36bb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 parameter may c
36bc0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 hange or.** be d
36bd0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 eallocated after
36be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36bf0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 value() returns
36c00 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
36c10 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ^A [protected s
36c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
36c30 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 ject may always
36c40 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e be used where an
36c50 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
36c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
36c70 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 object is requir
36c80 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a ed, so either.**
36c90 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 kind of [sqlite
36ca0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
36cb0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 can be used with
36cc0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
36cd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 .**.** If these
36ce0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
36cf0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 led from within
36d00 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 the different th
36d10 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 read.** than the
36d20 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 one containing
36d30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
36d40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
36d50 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a that received.*
36d60 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
36d70 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c ontext] pointer,
36d80 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
36d90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 undefined..*/.S
36da0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
36db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
36dc0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
36dd0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
36de0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
36df0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
36e00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
36e10 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
36e20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36e30 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f double);.SQLITE_
36e40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
36e50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
36e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36e70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
36e80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
36e90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36ea0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
36eb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
36ec0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 t void*, int);.S
36ed0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
36ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36ef0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
36f00 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
36f10 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
36f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
36f30 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 or_nomem(sqlite3
36f40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
36f50 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
36f60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36f70 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
36f80 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 ntext*, int);.SQ
36f90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
36fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
36fb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36fc0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
36fd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
36fe0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
36ff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37000 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
37010 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
37020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
37030 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ull(sqlite3_cont
37040 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
37050 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
37060 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
37070 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
37080 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
37090 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
370a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
370b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
370c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
370d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
370e0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
370f0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
37100 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
37110 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37120 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
37130 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
37140 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
37150 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
37160 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
37170 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 esult_text16be(s
37180 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
37190 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
371a0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
371b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
371c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
371d0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f t_value(sqlite3_
371e0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
371f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
37200 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
37210 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
37220 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
37230 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
37240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
37250 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
37260 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a ng Sequences.**.
37270 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
37280 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c ons add, remove,
37290 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f or modify a [co
372a0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 llation] associa
372b0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ted.** with the
372c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
372d0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
372e0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
372f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
37300 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
37310 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 llation is a UTF
37320 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
37330 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
37340 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
37350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
37360 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
37370 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
37380 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
37390 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 yte order for sq
373a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
373b0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e lation16()..** ^
373c0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 Collation names
373d0 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 that compare equ
373e0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 al according to
373f0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d [sqlite3_strnicm
37400 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 p()] are.** cons
37410 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 idered to be the
37420 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a same name..**.*
37430 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 * ^(The third ar
37440 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 gument (eTextRep
37450 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 ) must be one of
37460 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a the constants:.
37470 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
37480 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
37490 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 * <li> [SQLITE_U
374a0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e TF16LE],.** <li>
374b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
374c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
374d0 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a TE_UTF16], or.**
374e0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
374f0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a F16_ALIGNED]..**
37500 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 </ul>)^.** ^The
37510 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 eTextRep argume
37520 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 nt determines th
37530 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 e encoding of st
37540 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 rings passed.**
37550 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 to the collating
37560 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
37570 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a ck, xCallback..*
37580 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
37590 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 TF16] and [SQLIT
375a0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
375b0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 values for eTex
375c0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 tRep.** force st
375d0 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 rings to be UTF1
375e0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 6 with native by
375f0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 te order..** ^Th
37600 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f e [SQLITE_UTF16_
37610 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 ALIGNED] value f
37620 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 or eTextRep forc
37630 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 es strings to be
37640 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 gin.** on an eve
37650 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a n byte address..
37660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
37670 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 h argument, pArg
37680 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 , is an applicat
37690 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
376a0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a that is passed.
376b0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ** through as th
376c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
376d0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e to the collatin
376e0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
376f0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ack..**.** ^The
37700 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 fifth argument,
37710 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 xCallback, is a
37720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 pointer to the c
37730 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
37740 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 n..** ^Multiple
37750 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
37760 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 ons can be regis
37770 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
37780 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a same name but.**
37790 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
377a0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 eTextRep paramet
377b0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 ers and SQLite w
377c0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 ill use whicheve
377d0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 r.** function re
377e0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 quires the least
377f0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
37800 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a transformation..
37810 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c ** ^If the xCall
37820 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 back argument is
37830 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 NULL then the c
37840 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
37850 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e n is.** deleted.
37860 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c ^When all coll
37870 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 ating functions
37880 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 having the same
37890 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 name are deleted
378a0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 ,.** that collat
378b0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 ion is no longer
378c0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e usable..**.** ^
378d0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 The collating fu
378e0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 nction callback
378f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 is invoked with
37900 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 a copy of the pA
37910 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 rg .** applicati
37920 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 on data pointer
37930 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 and with two str
37940 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f ings in the enco
37950 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a ding specified.*
37960 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 * by the eTextRe
37970 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 p argument. The
37980 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37990 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 ion must return
379a0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 an.** integer th
379b0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 at is negative,
379c0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 zero, or positiv
379d0 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 e.** if the firs
379e0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 t string is less
379f0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c than, equal to,
37a00 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
37a10 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 the second,.**
37a20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 respectively. A
37a30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37a40 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 ion must always
37a50 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 return the same
37a60 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 answer.** given
37a70 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e the same inputs.
37a80 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 If two or more
37a90 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37aa0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 ions are registe
37ab0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 red.** to the sa
37ac0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d me collation nam
37ad0 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 e (using differe
37ae0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 nt eTextRep valu
37af0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 es) then all.**
37b00 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 must give an equ
37b10 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 ivalent answer w
37b20 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 hen invoked with
37b30 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 equivalent stri
37b40 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c ngs..** The coll
37b50 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d ating function m
37b60 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c ust obey the fol
37b70 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 lowing propertie
37b80 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 s for all.** str
37b90 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 ings A, B, and C
37ba0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
37bb0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 <li> If A==B the
37bc0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 n B==A..** <li>
37bd0 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 If A==B and B==C
37be0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c then A==C..** <
37bf0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 li> If A<B TH
37c00 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c EN B>A..** <l
37c10 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 i> If A<B and
37c20 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c B<C then A&l
37c30 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a t;C..** </ol>.**
37c40 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 .** If a collati
37c50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c ng function fail
37c60 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f s any of the abo
37c70 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 ve constraints a
37c80 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 nd that.** colla
37c90 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
37ca0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 registered and
37cb0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 used, then the
37cc0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
37cd0 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e te.** is undefin
37ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
37cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37d00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 llation_v2() wor
37d10 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
37d20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
37d30 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 ().** with the a
37d40 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 ddition that the
37d50 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 xDestroy callba
37d60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e ck is invoked on
37d70 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 pArg when.** th
37d80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
37d90 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e tion is deleted.
37da0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 .** ^Collating f
37db0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c unctions are del
37dc0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 eted when they a
37dd0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 re overridden by
37de0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 later.** calls
37df0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e to the collation
37e00 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 creation functi
37e10 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a ons or when the.
37e20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
37e30 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 nection] is clos
37e40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
37e50 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 3_close()]..**.*
37e60 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 * ^The xDestroy
37e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e callback is <u>n
37e80 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 ot</u> called if
37e90 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 the .** sqlite3
37ea0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
37eb0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 n_v2() function
37ec0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 fails. Applicat
37ed0 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 ions that invoke
37ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
37ef0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
37f00 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c ) with a non-NUL
37f10 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d L xDestroy argum
37f20 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 ent should .** c
37f30 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
37f40 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 code and dispose
37f50 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
37f60 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
37f70 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 .** themselves r
37f80 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 ather than expec
37f90 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 ting SQLite to d
37fa0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 eal with it for
37fb0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 them..** This is
37fc0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
37fd0 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 every other SQLi
37fe0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 te interface. T
37ff0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 he inconsistency
38000 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e .** is unfortun
38010 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 ate but cannot b
38020 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 e changed withou
38030 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 t breaking backw
38040 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 ards .** compati
38050 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 bility..**.** Se
38060 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 e also: [sqlite
38070 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
38080 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ed()] and [sqlit
38090 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
380a0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c ded16()]..*/.SQL
380b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
380c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
380d0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
380e0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
380f0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
38100 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
38110 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 *pArg,. int(*x
38120 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
38130 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
38140 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
38150 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
38160 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
38170 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
38180 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
38190 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
381a0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
381b0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
381c0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
381d0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
381e0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
381f0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
38200 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
38210 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
38220 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
38230 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
38240 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
38250 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d const void *zNam
38260 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 e,. int eTextRe
38270 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 p, . void *pArg
38280 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
38290 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
382a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
382b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
382c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
382d0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
382e0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
382f0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 To avoid having
38300 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 to register all
38310 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
38320 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 ces before a dat
38330 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 abase.** can be
38340 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 used, a single c
38350 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
38360 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
38370 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
38380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38390 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b ion] to be invok
383a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 ed whenever an u
383b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
383c0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 on.** sequence i
383d0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
383e0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 * ^If the functi
383f0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 on is registered
38400 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
38410 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
38420 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 ded() API,.** th
38430 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 en it is passed
38440 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 the names of und
38450 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
38460 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 sequences as st
38470 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 rings.** encoded
38480 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 in UTF-8. ^If s
38490 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
384a0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 _needed16() is u
384b0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 sed,.** the name
384c0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 s are passed as
384d0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e UTF-16 in machin
384e0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
384f0 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 der..** ^A call
38500 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 to either functi
38510 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 on replaces the
38520 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 existing collati
38530 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 on-needed callba
38540 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e ck..**.** ^(When
38550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
38560 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 invoked, the fi
38570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 rst argument pas
38580 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a sed is a copy.**
38590 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
385a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
385b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
385c0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ded() or.** sqli
385d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
385e0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 eded16(). The s
385f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
38600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a s the database.*
38610 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 * connection. T
38620 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
38630 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c t is one of [SQL
38640 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
38650 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 TE_UTF16BE],.**
38660 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
38670 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 LE], indicating
38680 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 the most desirab
38690 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 le form of the c
386a0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
386b0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 ence function re
386c0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 quired. The fou
386d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
386e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
386f0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c .** required col
38700 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e lation sequence.
38710 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c )^.**.** The cal
38720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 lback function s
38730 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 hould register t
38740 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 he desired colla
38750 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
38760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
38770 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c llation()], [sql
38780 69 74 65 33 5f 63 72 65 61 74 65 5f