0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 ent system. ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d ERSION "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 ID "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a . ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 nterfaces match
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 g constant. The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 e DLL. ^The.**
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 tion returns an
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 ION_NUMBER]. ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 constant whose
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 acro..**.** See
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 ceid(void);.int
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 * compile time.
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 d(). .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 erating.** over
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 on string. ^If
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 compile_options
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 OptName);.const
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 eadsafe. When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 READSAFE] macro
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 d. Without the
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 ently from more
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 .**.** Enabling
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 .** So if speed
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 s. But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 THREADSAFE=1 or
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 =2 then mutexes
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ()].** with the
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e ONFIG_MUTEX]. ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 se()].** is its
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 * Because there
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 defs for 64-bit
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 preferred type
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 definitions..**
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a clusive. ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 s .** between 0
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 use a lot of C
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 interface runs
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 st.** argument.
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 ments. ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 tion. ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 allback pointer
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 ed. ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 nger needed..**
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 g..**.** ^If an
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 and.** without
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 . ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 r each column.
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 nter. ^The 4th
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 r, a pointer.**
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 mments, then no
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 is a valid
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 cified by.**
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e o.** the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 sult codes],.**
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 LITE_ROLLBACK |
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a L 13 /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a TOPEN 14 /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 Unable to open
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 ITE_PROTOCOL
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 15 /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 SQLITE_EMPTY
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 16 /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 CHEMA 17
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 _TOOBIG 18
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f INT 19 /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 QLITE_ROW
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 100 /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 s]. However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 ** these result
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 arse-grained. T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 ld expect.** to
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 extended. It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EK
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 COVERY
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 EN_NOTEMPDIR
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 UPT_VTAB
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 DONLY_RECOVERY
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 _READONLY
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 0x00000001 /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 _READWRITE
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 0x00000002 /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 _CREATE
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 0x00000004 /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 _DELETEONCLOSE
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 0x00000008 /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 _EXCLUSIVE
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 0x00000010 /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 _AUTOPROXY
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 0x00000020 /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 _URI
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 0x00000040 /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 _MAIN_DB
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 0x00000100 /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 _TEMP_DB
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 0x00000200 /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 _TRANSIENT_DB
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 0x00000400 /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 _MAIN_JOURNAL
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 0x00000800 /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 _TEMP_JOURNAL
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 0x00001000 /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 _SUBJOURNAL
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 0x00002000 /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 _MASTER_JOURNAL
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 0x00004000 /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 _NOMUTEX
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 0x00008000 /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 _FULLMUTEX
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 0x00010000 /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 _SHAREDCACHE
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 0x00020000 /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 _PRIVATECACHE
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 0x00040000 /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 0x00080000 /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 Reserved:
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 he these.** bit
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 OMIC2K
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 OCAP_ATOMIC4K
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC8K
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 AP_ATOMIC16K
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 32K
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 END 0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 EQUENTIAL
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 E_WHEN_OPEN 0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 fsync()..**.**
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 gs. The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 flags determine
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 or rigorous or
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 ut among the.**
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 rted by SQLite,
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 only Mac OSX.**
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 cares about the
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 rsion 1 */. int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 **);. int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 gs);. void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 deleteFlag);.
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a ersion 2 */. /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 and only needs
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 to be supported
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 transaction. T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 his hint is not
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 se. The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ate database.**
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 n faster..**.**
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 VFS.** extends
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 -size to use.**
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 cating database
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 . See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 OMITTED] opcode
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 nal in order to
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 A synchronous |
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 us=OFF] is set,
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 this.** opcode
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 as doing so may
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 e it. .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 omatic.** retry
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 ions for the.**
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74 order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20 ness against.**
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ams. By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 e read,.** file
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 write, and file
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 73 delete opertions
86e0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
86f0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
8700: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
8710: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
8720: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
8730: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
8740: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
8750: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
8760: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
8770: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
8780: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
8790: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
87a0: 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73 20 those to values
87b0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
87c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
87d0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
87e0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
87f0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
8800: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
8810: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
8820: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
8830: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
8840: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
8850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
8860: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
8870: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
8880: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
8890: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
88a0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
88b0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
88c0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
88d0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
88e0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
88f0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
8900: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
8910: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
8920: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
8930: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
8940: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
8950: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
8960: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
8970: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
8980: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
8990: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
89a0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
89b0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
89c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
89d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
89e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 WAL] opcode is u
89f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
8a00: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
8a10: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 stent [WAL | Wri
8a20: 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73 65 te AHead Log] se
8a30: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 tting. By defau
8a40: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 lt, the auxiliar
8a50: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 y.** write ahead
8a60: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 log and shared
8a70: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 memory files use
8a80: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f d for transactio
8a90: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 n control.** are
8aa0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
8ab0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 eleted when the
8ac0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f latest connectio
8ad0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 n to the databas
8ae0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 e.** closes. Se
8af0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 tting persistent
8b00: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 WAL mode causes
8b10: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 those files to
8b20: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a persist after.**
8b30: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 close. Persist
8b40: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 ing the files is
8b50: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 useful when oth
8b60: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 er processes tha
8b70: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 t do not.** have
8b80: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f write permissio
8b90: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f n on the directo
8ba0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ry containing th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
8bc0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 want.** to read
8bd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
8be0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e e, as the WAL an
8bf0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 d shared memory
8c00: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 files must exist
8c10: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 .** in order for
8c20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f the database to
8c30: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 be readable. T
8c40: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
8c50: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
8c60: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8c70: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
8c80: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
8c90: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
8ca0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
8cb0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
8cc0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 sable persistent
8cd0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 WAL mode or 1 t
8ce0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 o enable persist
8cf0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e ent.** WAL mode.
8d00: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
8d10: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
8d20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
8d30: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
8d40: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e ** WAL persisten
8d50: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a ce setting..**.*
8d60: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
8d70: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
8d80: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
8d90: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
8da0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
8db0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
8dc0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
8dd0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
8de0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
8df0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
8e00: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
8e10: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
8e20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
8e30: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
8e40: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
8e50: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
8e60: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
8e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8e80: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
8e90: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 E 1.#defi
8ea0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f ne SQLITE_GET_LO
8eb0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
8ec0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
8ed0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_SET_LOCKPROXYF
8ee0: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 ILE 3.#defi
8ef0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
8f00: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
8f10: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
8f20: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
8f30: 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 T 5.#defi
8f40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
8f50: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
8f60: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
8f70: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
8f80: 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 NTER 7.#defi
8f90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
8fa0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 SYNC_OMITTED
8fb0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
8fd0: 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69 _RETRY 9.#defi
8fe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
8ff0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 PERSIST_WAL
9000: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
9010: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
9020: 45 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a E 11../*.*
9030: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
9040: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 x Handle.**.** T
9050: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 he mutex module
9060: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 within SQLite de
9070: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d fines [sqlite3_m
9080: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a utex] to be an.*
9090: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 * abstract type
90a0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 for a mutex obje
90b0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ct. The SQLite
90c0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 core never looks
90d0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 .** at the inter
90e0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
90f0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 on of an [sqlite
9100: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 3_mutex]. It on
9110: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 ly.** deals with
9120: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
9130: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
9140: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d object..**.** M
9150: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 utexes are creat
9160: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
9170: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
9180: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
9190: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
91a0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b x sqlite3_mutex;
91b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
91c0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
91d0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 bject.**.** An i
91e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 nstance of the s
91f0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
9200: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
9210: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a terface between.
9220: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f ** the SQLite co
9230: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 re and the under
9240: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
9250: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 system. The "vf
9260: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d s".** in the nam
9270: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 e of the object
9280: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 stands for "virt
9290: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 ual file system"
92a0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 . See.** the [V
92b0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e FS | VFS documen
92c0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 tation] for furt
92d0: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e her information.
92e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
92f0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e of the iVersion
9300: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 field is initia
9310: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 lly 1 but may be
9320: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 larger in.** fu
9330: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
9340: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 SQLite. Additi
9350: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 onal fields may
9360: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 be appended to t
9370: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 his.** object wh
9380: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 en the iVersion
9390: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 value is increas
93a0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 ed. Note that t
93b0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 he structure.**
93c0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
93d0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 fs object change
93e0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 s in the transac
93f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 tion between.**
9400: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
9410: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 .5.9 and 3.6.0 a
9420: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 nd yet the iVers
9430: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f ion field was no
9440: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a t.** modified..*
9450: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c *.** The szOsFil
9460: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 e field is the s
9470: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c ize of the subcl
9480: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 assed [sqlite3_f
9490: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ile].** structur
94a0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 e used by this V
94b0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 FS. mxPathname
94c0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c is the maximum l
94d0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 ength of.** a pa
94e0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 thname in this V
94f0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 FS..**.** Regist
9500: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 ered sqlite3_vfs
9510: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 objects are kep
9520: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
9530: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
9540: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
9550: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
9560: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
9570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
9580: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
9590: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
95a0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
95b0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
95c0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
95d0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
95e0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
95f0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
9600: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 . Neither the a
9610: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
9620: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 nor the VFS.** i
9630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
9640: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 ould use the pNe
9650: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a xt pointer..**.*
9660: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c * The pNext fiel
9670: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 d is the only fi
9680: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 eld in the sqlit
9690: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 e3_vfs.** struct
96a0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ure that SQLite
96b0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 will ever modify
96c0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f . SQLite will o
96d0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 nly access.** or
96e0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 modify this fie
96f0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 ld while holding
9700: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 a particular st
9710: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 atic mutex..** T
9720: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
9730: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 hould never modi
9740: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 fy anything with
9750: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
9760: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 fs.** object onc
9770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 e the object has
9780: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 been registered
9790: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d ..**.** The zNam
97a0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 e field holds th
97b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 e name of the VF
97c0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e S module. The n
97d0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 ame must.** be u
97e0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c nique across all
97f0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a VFS modules..**
9800: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
9810: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 s.xOpen]].** ^SQ
9820: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
9830: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 that the zFilena
9840: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 me parameter to
9850: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 xOpen.** is eith
9860: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
9870: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 r or string obta
9880: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 ined.** from xFu
9890: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 llPathname() wit
98a0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 h an optional su
98b0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e ffix added..** ^
98c0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 If a suffix is a
98d0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c dded to the zFil
98e0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c ename parameter,
98f0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 it will.** cons
9900: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 ist of a single
9910: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f "-" character fo
9920: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 llowed by no mor
9930: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 e than.** 10 alp
9940: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 hanumeric and/or
9950: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e "-" characters.
9960: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 .** ^SQLite furt
9970: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 her guarantees t
9980: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e hat.** the strin
9990: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
99a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
99b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
99c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 ** called. Becau
99d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f se of the previo
99e0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 us sentence,.**
99f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
9a00: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 e] can safely st
9a10: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
9a20: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
9a30: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
9a40: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
9a50: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
9a60: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 eason..** If the
9a70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
9a80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 eter to xOpen is
9a90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
9aa0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 then xOpen.** mu
9ab0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 st invent its ow
9ac0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 n temporary name
9ad0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 for the file.
9ae0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a ^Whenever the .*
9af0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 * xFilename para
9b00: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 meter is NULL it
9b10: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 will also be th
9b20: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a e case that the.
9b30: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 ** flags paramet
9b40: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 er will include
9b50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
9b60: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a ETEONCLOSE]..**.
9b70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
9b80: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 ument to xOpen()
9b90: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 includes all bi
9ba0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 ts set in.** the
9bb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
9bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
9bd0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b _v2()]. Or if [
9be0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
9bf0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
9c00: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 pen16()] is used
9c10: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 , then flags inc
9c20: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a ludes at least.*
9c30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
9c40: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
9c50: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
9c60: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 . .** If xOpen()
9c70: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
9c80: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
9c90: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
9ca0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
9cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
9cc0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
9cd0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
9ce0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
9cf0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 * ^(SQLite will
9d00: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
9d10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
9d20: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
9d30: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
9d40: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
9d50: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
9d60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
9d70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
9d80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
9d90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
9da0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
9db0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
9dc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
9dd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
9de0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
9df0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
9e00: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
9e10: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
9e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
9e30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
9e40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
9e50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
9e60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
9e70: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 OPEN_WAL].** </u
9e80: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 l>)^.**.** The f
9e90: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
9ea0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
9eb0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
9ec0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
9ed0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
9ee0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
9ef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
9f00: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
9f10: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
9f20: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
9f30: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
9f40: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
9f50: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
9f60: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
9f70: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
9f80: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
9f90: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
9fa0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
9fb0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
9fc0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
9fd0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
9fe0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
9ff0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
a000: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
a010: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
a020: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
a030: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
a040: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
a050: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
a060: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
a070: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
a080: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
a090: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
a0a0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
a0b0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
a0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
a0d0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
a0e0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
a0f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
a100: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
a110: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
a120: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
a130: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
a140: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
a150: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
a160: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
a170: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
a180: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
a190: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
a1a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
a1b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
a1c0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
a1d0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 for TEMP databas
a1e0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 es and their jou
a1f0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 rnals, transient
a200: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 .** databases, a
a210: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a nd subjournals..
a220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
a230: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
a240: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 E] flag is alway
a250: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e s used in conjun
a260: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 ction.** with th
a270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
a280: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 REATE] flag, whi
a290: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 ch are both dire
a2a0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 ctly.** analogou
a2b0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 s to the O_EXCL
a2c0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 and O_CREAT flag
a2d0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f s of the POSIX o
a2e0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 pen().** API. T
a2f0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 he SQLITE_OPEN_E
a300: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 XCLUSIVE flag, w
a310: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 hen paired with
a320: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f the .** SQLITE_O
a330: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 PEN_CREATE, is u
a340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
a350: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 that file should
a360: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 always.** be cr
a370: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 eated, and that
a380: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 it is an error i
a390: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 f it already exi
a3a0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 sts..** It is <i
a3b0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f >not</i> used to
a3c0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 indicate the fi
a3d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
a3e0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c ned .** for excl
a3f0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a usive access..**
a400: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a .** ^At least sz
a410: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 OsFile bytes of
a420: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 memory are alloc
a430: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a ated by SQLite.*
a440: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b * to hold the [
a450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
a460: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
a470: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
a480: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
a490: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 . The xOpen met
a4a0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 hod does not hav
a4b0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 e to.** allocate
a4c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 the structure;
a4d0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 it should just f
a4e0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 ill it in. Note
a4f0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 that.** the xOp
a500: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 en method must s
a510: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
a520: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 ile.pMethods to
a530: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 either.** a vali
a540: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 d [sqlite3_io_me
a550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 thods] object or
a560: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e to NULL. xOpen
a570: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 must do.** this
a580: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 even if the ope
a590: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 n fails. SQLite
a5a0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 expects that th
a5b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
a5c0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 Methods.** eleme
a5d0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 nt will be valid
a5e0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 after xOpen ret
a5f0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 urns regardless
a600: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a of the success.*
a610: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 * or failure of
a620: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a the xOpen call..
a630: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f **.** [[sqlite3_
a640: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a vfs.xAccess]].**
a650: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 ^The flags argu
a660: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
a670: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
a680: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
a690: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
a6a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
a6b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
a6c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
a6d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
a6e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
a6f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
a700: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
a710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
a720: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
a730: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
a740: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
a750: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
a760: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
a770: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 y..**.** ^SQLite
a780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
a790: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
a7a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
a7b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 s for the.** out
a7c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c put buffer xFull
a7d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 Pathname. The e
a7e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
a7f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
a800: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
a810: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
a820: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
a830: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
a840: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
a850: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
a860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
a870: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
a880: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
a890: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
a8a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
a8b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
a8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
a8d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
a8e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
a8f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
a900: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
a910: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
a920: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
a930: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
a940: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e Sleep(), xCurren
a950: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 tTime(), and xCu
a960: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
a970: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
a980: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
a990: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
a9a0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
a9b0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
a9c0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
a9d0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
a9e0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
a9f0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
aa00: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
aa10: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
aa20: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
aa30: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
aa40: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
aa50: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
aa60: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
aa70: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
aa80: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
aa90: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 s obtained..** T
aaa0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
aab0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 od causes the ca
aac0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 lling thread to
aad0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 sleep for at.**
aae0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 least the number
aaf0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 of microseconds
ab00: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 given. ^The xC
ab10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
ab20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
ab30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
ab40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
ab50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 nt date and time
ab60: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e as.** a floatin
ab70: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a g point value..*
ab80: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 * ^The xCurrentT
ab90: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
aba0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e d returns, as an
abb0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 integer, the Ju
abc0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 lian.** Day Numb
abd0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 er multiplied by
abe0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 86400000 (the n
abf0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 umber of millise
ac00: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 conds in .** a 2
ac10: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 4-hour day). .*
ac20: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
ac30: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 se the xCurrentT
ac40: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
ac50: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 d to get the cur
ac60: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 rent.** date and
ac70: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 time if that me
ac80: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c thod is availabl
ac90: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 e (if iVersion i
aca0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 s 2 or .** great
acb0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 er and the funct
acc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
acd0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c ot NULL) and wil
ace0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 l fall back.** t
acf0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 o xCurrentTime()
ad00: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 if xCurrentTime
ad10: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 Int64() is unava
ad20: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ilable..**.** ^T
ad30: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c he xSetSystemCal
ad40: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 l(), xGetSystemC
ad50: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 all(), and xNest
ad60: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 SystemCall() int
ad70: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e erfaces.** are n
ad80: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 ot used by the S
ad90: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 QLite core. The
ada0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 se optional inte
adb0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 rfaces are provi
adc0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 ded.** by some V
add0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 FSes to facilita
ade0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 te testing of th
adf0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f e VFS code. By o
ae00: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 verriding .** sy
ae10: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 stem calls with
ae20: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 functions under
ae30: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 its control, a t
ae40: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a est program can.
ae50: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c ** simulate faul
ae60: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e ts and error con
ae70: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 ditions that wou
ae80: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 ld otherwise be
ae90: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 difficult.** or
aea0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e impossible to in
aeb0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f duce. The set o
aec0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 f system calls t
aed0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 hat can be overr
aee0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 idden.** varies
aef0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 from one VFS to
af00: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f another, and fro
af10: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 m one version of
af20: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f the same VFS to
af30: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 the.** next. A
af40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
af50: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 use these inter
af60: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 faces must be pr
af70: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a epared for any.*
af80: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 * or all of thes
af90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 e interfaces to
afa0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 be NULL or for t
afb0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f heir behavior to
afc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 change.** from
afd0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 one release to t
afe0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 he next. Applic
aff0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 ations must not
b000: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 attempt to acces
b010: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 s.** any of thes
b020: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 e methods if the
b030: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 iVersion of the
b040: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 VFS is less tha
b050: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n 3..*/.typedef
b060: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
b070: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a fs sqlite3_vfs;.
b080: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
b090: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 qlite3_syscall_p
b0a0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 tr)(void);.struc
b0b0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a t sqlite3_vfs {.
b0c0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 int iVersion;
b0d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 /* St
b0e0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 ructure version
b0f0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c number (currentl
b100: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a y 3) */. int sz
b110: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
b120: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
b130: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
b140: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
b150: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
b160: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
b170: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
b180: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
b190: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
b1a0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
b1b0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
b1c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
b1d0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
b1e0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
b1f0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
b200: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
b210: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
b220: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
b230: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
b240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
b250: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
b260: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
b270: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
b280: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
b290: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
b2a0: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
b2b0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
b2c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
b2d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
b2e0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
b2f0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
b300: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
b310: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
b320: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
b330: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
b340: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
b350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
b360: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
b370: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
b380: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
b390: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
b3a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
b3b0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
b3c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
b3d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
b3e0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
b3f0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
b400: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
b410: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
b420: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
b430: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
b440: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
b450: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
b460: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
b470: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
b480: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
b490: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
b4a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
b4b0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
b4c0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
b4d0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
b4e0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
b4f0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
b500: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
b510: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
b520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
b530: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a har *);. /*. *
b540: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
b550: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
b560: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 on 1 of the sqli
b570: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 te_vfs object.
b580: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 ** definition.
b590: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f Those that follo
b5a0: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 w are added in v
b5b0: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 ersion 2 or late
b5c0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 r. */. int (*x
b5d0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
b5e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
b5f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b sqlite3_int64*);
b600: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
b610: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
b620: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 in versions 1 a
b630: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 nd 2 of the sqli
b640: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
b650: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 ** Those below
b660: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 are for version
b670: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 3 and greater..
b680: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 */. int (*xSet
b690: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
b6a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
b6b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
b6c0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
b6d0: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 );. sqlite3_sys
b6e0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 call_ptr (*xGetS
b6f0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
b700: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
b710: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 har *zName);. c
b720: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 onst char *(*xNe
b730: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 xtSystemCall)(sq
b740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
b750: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
b760: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
b770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
b780: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 in versions 1 th
b790: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 rough 3 of the s
b7a0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 qlite_vfs object
b7b0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 .. ** New field
b7c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
b7d0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 d in figure vers
b7e0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 ions. The iVers
b7f0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 ion. ** value w
b800: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 ill increment wh
b810: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 enever this happ
b820: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f ens. . */.};../
b830: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
b840: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
b850: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a cess VFS method.
b860: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
b870: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 ger constants ca
b880: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 n be used as the
b890: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
b8a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 to.** the xAcce
b8b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 ss method of an
b8c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
b8d0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 ject. They dete
b8e0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
b8f0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
b900: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
b910: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
b920: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
b930: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
b940: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
b950: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
b960: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
b970: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
b980: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
b990: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
b9a0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
b9b0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
b9c0: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 ether the named
b9d0: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 directory is bot
b9e0: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
b9f0: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f ritable.** (in o
ba00: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 ther words, if f
ba10: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 iles can be adde
ba20: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 d, removed, and
ba30: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a renamed within.*
ba40: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 * the directory)
ba50: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
ba60: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
ba70: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 constant is cur
ba80: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 rently used only
ba90: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 by the.** [temp
baa0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
bab0: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 pragma], though
bac0: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e this could chan
bad0: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a ge in a future.*
bae0: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c * release of SQL
baf0: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c ite..** With SQL
bb00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c ITE_ACCESS_READ,
bb10: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
bb20: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
bb30: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
bb40: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 s readable. The
bb50: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
bb60: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a EAD constant is.
bb70: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 ** currently unu
bb80: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d sed, though it m
bb90: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 ight be used in
bba0: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 a future release
bbb0: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a of.** SQLite..*
bbc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
bbd0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 _ACCESS_EXISTS
bbe0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
bbf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
bc00: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 ITE 1 /* Used
bc10: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 by PRAGMA temp_s
bc20: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a tore_directory *
bc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
bc40: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 _ACCESS_READ
bc50: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2 /* Unused
bc60: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
bc70: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
bc80: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d e xShmLock VFS m
bc90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
bca0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
bcb0: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 nts define the v
bcc0: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f arious locking o
bcd0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c perations.** all
bce0: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d owed by the xShm
bcf0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b Lock method of [
bd00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
bd10: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c ds]. The.** fol
bd20: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f lowing are the o
bd30: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e nly legal combin
bd40: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 ations of flags
bd50: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f to the.** xShmLo
bd60: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a ck method:.**.**
bd70: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 <ul>.** <li> S
bd80: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c QLITE_SHM_LOCK |
bd90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
bda0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
bdb0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
bdc0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
bdd0: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
bde0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
bdf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
be00: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
be10: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
be20: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
be30: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a IVE.** </ul>.**.
be40: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e ** When unlockin
be50: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 g, the same SHAR
be60: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 ED or EXCLUSIVE
be70: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 flag must be sup
be80: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 plied as.** was
be90: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 given no the cor
bea0: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e responding lock.
beb0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 .**.** The xSh
bec0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e mLock method can
bed0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 transition betw
bee0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
bef0: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 SHARED or.** be
bf00: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 tween unlocked a
bf10: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 nd EXCLUSIVE. I
bf20: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 t cannot transit
bf30: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 ion between SHAR
bf40: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 ED.** and EXCLUS
bf50: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 IVE..*/.#define
bf60: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
bf70: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e K 1.#defin
bf80: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 e SQLITE_SHM_LOC
bf90: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 K 2.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 ine SQLITE_SHM_S
bfb0: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 HARED 4.#d
bfc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
bfd0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a _EXCLUSIVE 8.
bfe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
bff0: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 Maximum xShmLoc
c000: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 k index.**.** Th
c010: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
c020: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f d on [sqlite3_io
c030: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 _methods] may us
c040: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 e values.** betw
c050: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 een 0 and this u
c060: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 pper bound as it
c070: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d s "offset" argum
c080: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 ent..** The SQLi
c090: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 te core will nev
c0a0: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 er attempt to ac
c0b0: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 quire or release
c0c0: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 a.** lock outsi
c0d0: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 de of this range
c0e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
c0f0: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 TE_SHM_NLOCK
c100: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 8.../*.** CA
c110: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 PI3REF: Initiali
c120: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ze The SQLite Li
c130: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 brary.**.** ^The
c140: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
c150: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e ize() routine in
c160: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a itializes the.**
c170: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
c180: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
c190: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e hutdown() routin
c1a0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 e.** deallocates
c1b0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 any resources t
c1c0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 hat were allocat
c1d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
c1e0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 itialize()..** T
c1f0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
c200: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 e designed to ai
c210: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 d in process ini
c220: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a tialization and.
c230: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 ** shutdown on e
c240: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
c250: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 Workstation ap
c260: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 plications using
c270: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 .** SQLite norma
c280: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 lly do not need
c290: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 to invoke either
c2a0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
c2b0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
c2c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
c2d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
c2e0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
c2f0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
c300: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
c310: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
c320: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
c330: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
c340: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
c350: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
c360: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
c370: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
c380: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
c390: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
c3a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
c3b0: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 down(). ^(Only
c3c0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
c3d0: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
c3e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
c3f0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
c400: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
c410: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
c420: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
c430: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
c440: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
c450: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 n() is an "effec
c460: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
c470: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a is the first.**
c480: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
c490: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 _shutdown() sinc
c4a0: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 e the last sqlit
c4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
c4c0: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 ^(Only.** an e
c4d0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f ffective call to
c4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
c4f0: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 n() does any dei
c500: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a nitialization..*
c510: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 * All other vali
c520: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 d calls to sqlit
c530: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 e3_shutdown() ar
c540: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
c550: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 s.)^.**.** The s
c560: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
c570: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 e() interface is
c580: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 threadsafe, but
c590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
c5a0: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 n().** is not.
c5b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
c5c0: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 down() interface
c5d0: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 must only be ca
c5e0: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 lled from a.** s
c5f0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 ingle thread. A
c600: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 ll open [databas
c610: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d e connections] m
c620: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e ust be closed an
c630: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 d all.** other S
c640: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 QLite resources
c650: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 must be dealloca
c660: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 ted prior to inv
c670: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 oking.** sqlite3
c680: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a _shutdown()..**.
c690: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 ** Among other t
c6a0: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f hings, ^sqlite3_
c6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c initialize() wil
c6c0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 l invoke.** sqli
c6d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
c6e0: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 Similarly, ^sqli
c6f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
c700: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 * will invoke sq
c710: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a lite3_os_end()..
c720: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
c730: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
c740: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
c750: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
c760: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 uccess..** ^If f
c770: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 or some reason,
c780: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
c790: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 ze() is unable t
c7a0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 o initialize.**
c7b0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 the library (per
c7c0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c haps it is unabl
c7d0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 e to allocate a
c7e0: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 needed resource
c7f0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 such.** as a mut
c800: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 ex) it returns a
c810: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
c820: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
c830: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 E_OK]..**.** ^Th
c840: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
c850: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
c860: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 s called interna
c870: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 lly by many othe
c880: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
c890: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 rfaces so that a
c8a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
c8b0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e ually does not n
c8c0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 eed to.** invoke
c8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
c8e0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ize() directly.
c8f0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 For example, [s
c900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
c910: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f * calls sqlite3_
c920: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 initialize() so
c930: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
c940: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ry will be autom
c950: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 atically.** init
c960: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 ialized when [sq
c970: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 lite3_open()] is
c980: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 called if it ha
c990: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c s not be initial
c9a0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e ized.** already.
c9b0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 ^However, if S
c9c0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
c9d0: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 d with the [SQLI
c9e0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
c9f0: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ].** compile-tim
ca00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 e option, then t
ca10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c he automatic cal
ca20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ls to sqlite3_in
ca30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 itialize().** ar
ca40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 e omitted and th
ca50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
ca60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f st call sqlite3_
ca70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
ca80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 ectly.** prior t
ca90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
caa0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
cab0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d ce. For maximum
cac0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a portability,.**
cad0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
cae0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
caf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f ions always invo
cb00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
cb10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 alize().** direc
cb20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 tly prior to usi
cb30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
cb40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
cb50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a Future releases.
cb60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ** of SQLite may
cb70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 require this.
cb80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
cb90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 the behavior exh
cba0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 ibited.** when S
cbb0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
cbc0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f d with [SQLITE_O
cbd0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 MIT_AUTOINIT] mi
cbe0: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a ght become the.*
cbf0: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 * default behavi
cc00: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 or in some futur
cc10: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
cc20: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ite..**.** The s
cc30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
cc40: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 routine does op
cc50: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
cc60: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 pecific.** initi
cc70: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 alization of the
cc80: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
cc90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
cca0: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e _end().** routin
ccb0: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 e undoes the eff
ccc0: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ect of sqlite3_o
ccd0: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 s_init(). Typic
cce0: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 al tasks.** perf
ccf0: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 ormed by these r
cd00: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 outines include
cd10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 allocation or de
cd20: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
cd30: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 static resource
cd40: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f s, initializatio
cd50: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 n of global vari
cd60: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e ables,.** settin
cd70: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b g up a default [
cd80: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 sqlite3_vfs] mod
cd90: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 ule, or setting
cda0: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 up.** a default
cdb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 configuration us
cdc0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e ing [sqlite3_con
cdd0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 fig()]..**.** Th
cde0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
cdf0: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b ould never invok
ce00: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 e either sqlite3
ce10: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 _os_init().** or
ce20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
ce30: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 ) directly. The
ce40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
ce50: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a uld only invoke.
ce60: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ** sqlite3_initi
ce70: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 alize() and sqli
ce80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 te3_shutdown().
ce90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
cea0: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 init().** interf
ceb0: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 ace is called au
cec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
ced0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
cee0: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 e() and.** sqlit
cef0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 e3_os_end() is c
cf00: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 alled by sqlite3
cf10: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 _shutdown(). Ap
cf20: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 propriate.** imp
cf30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
cf40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
cf50: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
cf60: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 s_end().** are b
cf70: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
cf80: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
cf90: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 iled for Unix, W
cfa0: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e indows, or OS/2.
cfb0: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d .** When [custom
cfc0: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 builds | built
cfd0: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f for other platfo
cfe0: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 rms].** (using t
cff0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 he [SQLITE_OS_OT
d000: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 HER=1] compile-t
d010: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 ime.** option) t
d020: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
d030: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 ust supply a sui
d040: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
d050: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 tion for.** sqli
d060: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
d070: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
d080: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 (). An applicat
d090: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ion-supplied.**
d0a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
d0b0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
d0c0: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f t() or sqlite3_o
d0d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 s_end().** must
d0e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
d0f0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e K] on success an
d100: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 d some other [er
d110: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a ror code] upon.*
d120: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e * failure..*/.in
d130: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
d140: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 lize(void);.int
d150: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d160: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
d170: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 te3_os_init(void
d180: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
d190: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a s_end(void);../*
d1a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
d1b0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 nfiguring The SQ
d1c0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
d1d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
d1e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
d1f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
d200: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 e global configu
d210: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
d220: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f s to SQLite in o
d230: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c rder to tune SQL
d240: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 ite to the speci
d250: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 fic needs of.**
d260: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
d270: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f The default co
d280: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 nfiguration is r
d290: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d ecommended for m
d2a0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ost.** applicati
d2b0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 ons and so this
d2c0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c routine is usual
d2d0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 ly not necessary
d2e0: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 . It is.** prov
d2f0: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 ided to support
d300: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e rare application
d310: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e s with unusual n
d320: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eeds..**.** The
d330: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
d340: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
d350: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 t threadsafe. T
d360: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
d370: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 * must insure th
d380: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 at no other SQLi
d390: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 te interfaces ar
d3a0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 e invoked by oth
d3b0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 er.** threads wh
d3c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ile sqlite3_conf
d3d0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ig() is running.
d3e0: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 Furthermore, s
d3f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a qlite3_config().
d400: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 ** may only be i
d410: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 nvoked prior to
d420: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 library initiali
d430: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 zation using.**
d440: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
d450: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
d460: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c shutdown by [sql
d470: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
d480: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
d490: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c _config() is cal
d4a0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
d4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
d4c0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b and before.** [
d4d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d4e0: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c ()] then it will
d4f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d return SQLITE_M
d500: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 ISUSE..** Note,
d510: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 however, that ^s
d520: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
d530: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
d540: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
d550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
d560: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
d570: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
d580: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
d590: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
d5a0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
d5b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
d5c0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e integer.** [con
d5d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
d5e0: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e n] that determin
d5f0: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 es.** what prope
d600: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 rty of SQLite is
d610: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 to be configure
d620: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 d. Subsequent a
d630: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 rguments.** vary
d640: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
d650: 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e e [configuration
d660: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 option].** in t
d670: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
d680: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 t..**.** ^When a
d690: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
d6a0: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
d6b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
d6c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
d6d0: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f K]..** ^If the o
d6e0: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
d6f0: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
d700: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
d710: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
d720: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
d730: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
d740: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
d750: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
d760: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
d770: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
d780: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
d790: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
d7a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
d7b0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
d7c0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
d7d0: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
d7e0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
d7f0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
d800: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
d810: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
d820: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
d830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
d840: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
d850: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
d860: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
d870: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
d880: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
d890: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
d8a0: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
d8b0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
d8c0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
d8d0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
d8e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
d8f0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
d900: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
d910: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
d920: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
d930: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
d940: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
d950: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
d960: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
d970: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
d980: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
d990: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
d9a0: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
d9b0: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
d9c0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
d9d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
d9e0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
d9f0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
da00: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
da10: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
da20: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ssful..*/.int sq
da30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
da40: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
da50: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
da60: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
da70: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
da80: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
da90: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
daa0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
dab0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
dac0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
dad0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
dae0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
daf0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
db00: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
db10: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
db20: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
db30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
db40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
db50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
db60: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
db70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
db80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
db90: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
dba0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
dbb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
dbc0: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
dbd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
dbe0: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
dbf0: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
dc00: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
dc10: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
dc20: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
dc30: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
dc40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
dc50: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
dc60: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
dc70: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
dc80: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
dc90: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
dca0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
dcb0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
dcc0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
dcd0: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
dce0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
dcf0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
dd00: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
dd10: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
dd20: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
dd30: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
dd40: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
dd50: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
dd60: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
dd70: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
dd80: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
dd90: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
dda0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
ddb0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
ddc0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
ddd0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
dde0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ddf0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
de00: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
de10: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
de20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
de30: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
de40: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
de50: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
de60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
de70: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
de80: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
de90: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
dea0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
deb0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
dec0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
ded0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
dee0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
def0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
df00: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
df10: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
df20: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
df30: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
df40: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
df50: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
df60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
df70: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
df80: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
df90: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
dfa0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
dfb0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
dfc0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
dfd0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
dfe0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
dff0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
e000: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
e010: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
e020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
e030: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
e040: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
e050: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
e060: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
e070: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
e080: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
e090: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
e0a0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
e0b0: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
e0c0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
e0d0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
e0e0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
e0f0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
e100: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
e110: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
e120: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
e130: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
e140: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
e150: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
e160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
e170: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
e180: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
e190: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
e1a0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
e1b0: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
e1c0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
e1d0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
e1e0: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
e1f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
e200: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
e210: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
e220: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
e230: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
e240: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
e250: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
e260: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
e270: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
e280: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
e290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
e2a0: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
e2b0: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
e2c0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
e2d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
e2e0: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 r. (For example
e2f0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
e300: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
e310: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
e320: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
e330: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
e340: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
e350: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
e360: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
e370: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
e380: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
e390: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
e3a0: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
e3b0: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
e3c0: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
e3d0: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
e3e0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
e3f0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
e400: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
e410: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
e420: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
e430: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
e440: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
e450: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
e460: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
e470: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
e480: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
e490: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
e4a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
e4b0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
e4c0: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
e4d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
e4e0: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
e4f0: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
e500: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
e510: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
e520: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
e530: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
e540: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
e550: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
e560: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
e570: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
e580: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
e590: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
e5a0: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
e5b0: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
e5c0: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
e5d0: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
e5e0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
e5f0: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
e600: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
e610: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
e620: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
e630: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
e640: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
e650: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
e660: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
e670: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
e680: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
e690: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
e6a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
e6b0: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
e6c0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
e6d0: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
e6e0: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
e6f0: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
e700: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
e710: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
e720: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
e730: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
e740: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
e750: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
e760: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
e770: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
e780: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
e790: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
e7a0: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
e7b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
e7c0: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
e7d0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
e7e0: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
e7f0: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
e800: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
e810: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
e820: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
e830: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
e840: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
e850: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
e860: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
e870: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
e880: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
e890: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
e8a0: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
e8b0: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
e8c0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
e8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
e8e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
e8f0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
e900: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
e910: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
e920: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
e930: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
e940: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
e950: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
e960: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
e970: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
e980: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
e990: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
e9a0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
e9b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
e9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e9d0: 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on}.**.** These
e9e0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
e9f0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
ea00: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
ea10: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
ea20: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
ea30: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
ea40: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
ea50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
ea60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
ea70: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
ea80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
ea90: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
eaa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
eab0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
eac0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
ead0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
eae0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
eaf0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
eb00: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
eb10: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
eb20: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
eb30: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
eb40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
eb50: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
eb60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
eb70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
eb80: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
eba0: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
ebb0: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
ebc0: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
ebd0: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
ebe0: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
ebf0: 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
ec00: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
ec10: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAD]] <dt>SQLITE
ec20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
ec30: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
ec40: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
ec50: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
ec60: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
ec70: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
ec80: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
ec90: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 e] to Single-thr
eca0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
ecb0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
ecc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
ecd0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
ece0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
ecf0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
ed00: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
ed10: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
ed20: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
ed30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
ed40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
ed50: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
ed60: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
ed70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
ed80: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
ed90: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
eda0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 change the [thre
edb0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d ading mode] from
edc0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 its default.**
edd0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d value of Single-
ede0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 thread and so [s
edf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
ee00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a will return .**
ee10: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
ee20: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
ee30: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
ee40: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a _SINGLETHREAD.**
ee50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
ee60: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
ee70: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
ee80: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 G_MULTITHREAD]]
ee90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
eea0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 G_MULTITHREAD</d
eeb0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
eec0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
eed0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
eee0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
eef0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
ef00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d ading mode] to M
ef10: 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e ulti-thread. In
ef20: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
ef30: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 disables.** mut
ef40: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 exing on [databa
ef50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
ef60: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
ef70: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
ef80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
ef90: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ion is responsib
efa0: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 le for serializi
efb0: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 ng access to.**
efc0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
efd0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
efe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
eff0: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 . But other mut
f000: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
f010: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 led so that SQLi
f020: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 te will be safe
f030: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 to use in a mult
f040: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e i-threaded.** en
f050: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e vironment as lon
f060: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 g as no two thre
f070: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ads attempt to u
f080: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b se the same.** [
f090: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f0a0: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 ion] at the same
f0b0: 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 time. ^If SQLi
f0c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
f0d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
f0e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
f0f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
f100: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
f110: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
f120: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
f130: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d ble to set the M
f140: 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
f150: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
f160: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
f170: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
f180: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
f190: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
f1a0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
f1b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
f1c0: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
f1d0: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
f1e0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
f1f0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 IG_SERIALIZED]]
f200: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
f210: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
f220: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
f230: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
f240: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
f250: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
f260: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
f270: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
f280: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
f290: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
f2a0: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
f2b0: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
f2c0: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
f2d0: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
f2e0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
f2f0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
f300: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
f310: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
f320: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
f330: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
f340: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
f350: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
f360: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
f370: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
f380: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
f390: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
f3a0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
f3b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f3c0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
f3d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
f3e0: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
f3f0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
f400: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
f410: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
f420: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
f430: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
f440: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
f450: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
f460: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
f470: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
f480: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
f490: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
f4a0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
f4b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
f4c0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
f4d0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
f4e0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
f4f0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
f500: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
f510: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
f520: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
f530: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
f540: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
f550: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
f560: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
f570: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
f580: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f590: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
f5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
f5b0: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
f5c0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
f5d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
f5e0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
f5f0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
f600: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
f610: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
f620: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
f630: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
f640: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
f650: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
f660: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
f670: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
f680: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
f690: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
f6a0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
f6b0: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
f6c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
f6d0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
f6e0: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
f6f0: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
f700: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
f710: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
f720: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
f730: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
f740: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
f750: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
f760: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
f770: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
f780: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
f790: 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e GETMALLOC]] <dt>
f7a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
f7b0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
f7c0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
f7d0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
f7e0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
f7f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
f800: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
f810: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
f820: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
f830: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
f840: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
f850: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
f860: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
f870: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
f880: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
f890: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
f8a0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
f8b0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
f8c0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
f8d0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
f8e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
f8f0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
f900: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 er that simulati
f910: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ons memory alloc
f920: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 ation failure or
f930: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 .** tracks memor
f940: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 y usage, for exa
f950: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a mple. </dd>.**.*
f960: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
f970: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 G_MEMSTATUS]] <d
f980: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
f990: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
f9a0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
f9b0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
f9c0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
f9d0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 e int, interpret
f9e0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c ed as a .** bool
f9f0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
fa00: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
fa10: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
fa20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
fa30: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 on .** statistic
fa40: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
fa50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
fa60: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
fa70: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c led, the .** fol
fa80: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
fa90: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
faa0: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
fab0: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
fac0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
fad0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
fae0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
faf0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
fb00: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
fb10: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
fb20: 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
fb30: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
fb40: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f tatus()].** </
fb50: 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
fb60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
fb70: 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
fb80: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
fb90: 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
fba0: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
fbb0: 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
fbc0: 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
fbd0: 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
fbe0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
fbf0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
fc00: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
fc10: 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
fc20: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
fc30: 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
fc40: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
fc50: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
fc60: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
fc70: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
fc80: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
fc90: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
fca0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 n use for.** scr
fcb0: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 atch memory. Th
fcc0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
fcd0: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e guments: A poin
fce0: 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
fcf0: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
fd00: 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
fd10: 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c h the scratch al
fd20: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
fd30: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
fd40: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
fd50: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
fd60: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
fd70: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
fd80: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
fd90: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 ations (N). The
fda0: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 sz.** argument
fdb0: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 must be a multip
fdc0: 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 le of 16..** The
fdd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
fde0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 must be a pointe
fdf0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 r to an 8-byte a
fe00: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a ligned buffer.**
fe10: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
fe20: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
fe30: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
fe40: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 ll use no more t
fe50: 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 han two scratch
fe60: 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
fe70: 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f ad. So.** N sho
fe80: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 uld be set to tw
fe90: 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 ice the expected
fea0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
feb0: 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e of threads..** ^
fec0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
fed0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 r require a scra
fee0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
fef0: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a is more than 6.*
ff00: 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 * times the data
ff10: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 base page size.
ff20: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
ff30: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
ff40: 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d l.** scratch mem
ff50: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ory beyond what
ff60: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
ff70: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
ff80: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a n option, then .
ff90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
ffa0: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 oc()] will be us
ffb0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
ffc0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c memory needed.<
ffd0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
ffe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
fff0: 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
10000 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
10010 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
10020 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
10030 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
10040 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
10050 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
10060 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 e for.** the dat
10070 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 abase page cache
10080 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c with the defaul
10090 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
100a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a lementation. .*
100b0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 * This configura
100c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 tion should not
100d0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 be used if an ap
100e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
100f0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
10100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
10110 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
10130 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a PCACHE option..*
10140 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
10150 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 e arguments to t
10160 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f his option: A po
10170 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 inter to 8-byte
10180 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 aligned.** memor
10190 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 y, the size of e
101a0 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 ach page buffer
101b0 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 (sz), and the nu
101c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e mber of pages (N
101d0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 )..** The sz arg
101e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
101f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
10200 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 largest database
10210 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 page.** (a powe
10220 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e r of two between
10230 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 512 and 32768)
10240 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 plus a little ex
10250 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tra for each.**
10260 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
10270 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 he page header s
10280 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 ize is 20 to 40
10290 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 bytes depending
102a0 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 on.** the host a
102b0 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 rchitecture. ^I
102c0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
102d0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
102e0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
102f0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 to make sz a lit
10300 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 tle too large.
10310 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
10320 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
10330 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
10340 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
10350 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
10360 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 mory..** ^SQLite
10370 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 will use the me
10380 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 mory provided by
10390 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
103a0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 ent to satisfy i
103b0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 ts.** memory nee
103c0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 ds for the first
103d0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 N pages that it
103e0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 adds to cache.
103f0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a ^If additional.
10400 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 ** page cache me
10410 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 mory is needed b
10420 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
10430 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f ovided by this o
10440 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 ption, then.** S
10450 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 QLite goes to [s
10460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
10470 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f for the additio
10480 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 nal storage spac
10490 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 e..** The pointe
104a0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
104b0 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 rgument must.**
104c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
104d0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
104e0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
104f0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
10500 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 e.** will be und
10510 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
10520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
10530 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
10540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
10550 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
10560 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
10570 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
10580 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
10590 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
105a0 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 .** for all of i
105b0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
105c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
105d0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ds beyond those
105e0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
105f0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
10600 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b G_SCRATCH] and [
10610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
10620 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 GECACHE]..** The
10630 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
10640 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 uments: An 8-byt
10650 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
10660 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
10670 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
10680 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
10690 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
106a0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
106b0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
106c0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
106d0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
106e0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
106f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
10700 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
10710 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
10720 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
10730 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
10740 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
10750 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
10760 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
10770 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
10780 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
10790 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
107a0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
107b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 s not NULL and e
107c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
107d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
107e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
107f0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 LE_MEMSYS5] are
10800 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 defined, then th
10810 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
10820 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
10830 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
10840 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
10850 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
10860 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
10870 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
10880 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
10890 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
108a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
108b0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
108c0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
108d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
108e0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
108f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
10900 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
10910 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
10920 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 t 2^12. Reasonab
10930 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
10940 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
10950 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
10960 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2^5 through 2^8
10970 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
10980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
10990 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
109a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 CONFIG_MUTEX</dt
109b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
109c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
109d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
109e0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
109f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
10a00 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
10a10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
10a20 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
10a30 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
10a40 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
10a50 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
10a60 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
10a70 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
10a80 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 ce.** the mutex
10a90 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
10aa0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
10ab0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
10ac0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f opy of the.** co
10ad0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
10ae0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
10af0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
10b00 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
10b10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
10b20 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
10b30 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
10b40 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
10b50 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
10b60 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
10b70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
10b80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
10b90 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
10ba0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
10bb0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
10bc0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
10bd0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
10be0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
10bf0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
10c00 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
10c10 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
10c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
10c30 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
10c40 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
10c50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
10c60 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
10c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
10c80 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
10c90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
10ca0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
10cb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
10cc0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
10cd0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
10ce0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
10cf0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
10d00 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
10d10 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
10d20 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a mutex_methods].*
10d30 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
10d40 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
10d50 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
10d60 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
10d70 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
10d80 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
10d90 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
10da0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f fault mutex allo
10db0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
10dc0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
10dd0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 r used to track
10de0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 mutex usage for
10df0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 performance.** p
10e00 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 rofiling or test
10e10 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 ing, for example
10e20 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 . ^If SQLite i
10e30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
10e40 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
10e50 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
10e60 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
10e70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
10e80 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
10e90 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
10ea0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
10eb0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
10ec0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
10ed0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
10ee0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
10ef0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
10f00 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f NFIG_GETMUTEX co
10f10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
10f20 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
10f30 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
10f40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
10f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
10f60 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c KASIDE]] <dt>SQL
10f70 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
10f80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
10f90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
10fa0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
10fb0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
10fc0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a ne the default.*
10fd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
10fe0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b ion for the look
10ff0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
11000 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a ocator on each.*
11010 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
11020 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 ection]. The fi
11030 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
11040 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
11050 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
11060 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
11070 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
11080 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
11090 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
110a0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
110b0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 nnection.)^ ^(T
110c0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
110d0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c the.** <i>defaul
110e0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
110f0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
11100 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
11110 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f SIDE].** verb to
11120 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
11130 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 fig()] can be us
11140 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
11150 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f lookaside.** co
11160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 nfiguration on i
11170 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 ndividual connec
11180 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a tions.)^ </dd>.*
11190 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
111a0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64 NFIG_PCACHE]] <d
111b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
111c0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c PCACHE</dt>.** <
111d0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
111e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
111f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
11200 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
11210 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ** an [sqlite3_p
11220 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
11230 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
11240 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 ect specifies th
11250 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 e interface.** t
11260 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
11270 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
11280 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 tion.)^ ^SQLite
11290 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
112a0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 the.** object a
112b0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 nd uses it for p
112c0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
112d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 allocations.</d
112e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
112f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
11300 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
11310 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
11320 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
11330 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
11340 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
11350 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
11360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
11370 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
11380 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
11390 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 SQLite copies
113a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
113b0 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 * page cache imp
113c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f lementation into
113d0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 that object.)^
113e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
113f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d LITE_CONFIG_LOG]
11400 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11410 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 FIG_LOG</dt>.**
11420 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
11430 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
11440 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
11450 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
11460 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
11470 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
11480 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
11490 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
114a0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
114b0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
114c0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
114d0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
114e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
114f0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
11500 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
11510 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
11520 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
11530 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
11540 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
11550 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
11560 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
11570 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
11580 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
11590 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
115a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
115b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
115c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
115d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
115e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
115f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
11600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
11610 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
11620 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
11630 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
11640 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
11650 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
11660 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
11670 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
11680 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
11690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
116a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
116b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
116c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
116d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
116e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
116f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
11700 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
11710 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
11720 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
11730 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
11740 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
11750 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
11760 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
11770 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
11780 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
11790 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
117a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
117b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
117c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
117d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
117e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
117f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
11800 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
11810 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
11820 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
11830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
11840 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
11850 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
11860 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
11870 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
11880 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 URI]] <dt>SQLITE
11890 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c _CONFIG_URI.** <
118a0 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 dd> This option
118b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
118c0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
118d0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f int. If non-zero
118e0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 , then.** URI ha
118f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
11900 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 ly enabled. If t
11910 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
11920 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 zero, then URI h
11930 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c andling.** is gl
11940 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e obally disabled.
11950 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 If URI handling
11960 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 is globally ena
11970 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 bled, all filena
11980 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f mes.** passed to
11990 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
119a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
119b0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
119c0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a _open16()] or.**
119d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
119e0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 rt of [ATTACH] c
119f0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 ommands are inte
11a00 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c rpreted as URIs,
11a10 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f regardless.** o
11a20 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
11a30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
11a40 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 N_URI] flag is s
11a50 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 et when the data
11a60 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
11a70 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 on is opened. If
11a80 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 it is globally
11a90 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 disabled, filena
11aa0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 mes are.** only
11ab0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
11ac0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 RIs if the SQLIT
11ad0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 E_OPEN_URI flag
11ae0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a is set when the.
11af0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
11b00 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
11b10 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 . By default, UR
11b20 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
11b30 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c obally.** disabl
11b40 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 ed. The default
11b50 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 value may be cha
11b60 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e nged by compilin
11b70 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 g with the.** [S
11b80 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 QLITE_USE_URI] s
11b90 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a ymbol defined..*
11ba0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
11bb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
11bc0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
11bd0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
11be0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
11bf0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
11c00 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
11c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
11c20 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
11c30 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
11c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
11c50 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
11c60 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
11c70 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
11c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
11c90 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
11ca0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
11cb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
11cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
11cd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
11ce0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
11cf0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
11d00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
11d10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
11d20 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
11d30 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
11d40 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
11d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
11d60 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
11d70 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
11d80 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
11d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
11da0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
11db0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
11dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
11dd0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
11de0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
11df0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
11e00 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
11e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
11e20 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
11e30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
11e40 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
11e50 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
11e60 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
11e70 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
11e80 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
11e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
11ea0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
11eb0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
11ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
11ed0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
11ee0 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 14 /* sqli
11ef0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
11f00 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
11f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
11f20 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a PCACHE 15 /*
11f30 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
11f40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
11f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
11f60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 G_LOG 1
11f70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 6 /* xFunc, voi
11f80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d* */.#define SQ
11f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
11fa0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 17 /*
11fb0 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 int */../*.** CA
11fc0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
11fd0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 Connection Conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
11ff0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
12000 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
12010 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
12020 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
12030 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
12040 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
12050 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
12060 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
12070 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
12080 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
12090 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
120a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
120b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
120c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
120d0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
120e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
120f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
12100 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
12110 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
12120 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
12130 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
12140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
12150 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
12160 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
12170 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
12180 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 ^The [sqlite3_d
12190 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
121a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
121b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
121c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
121d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
121e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
121f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
12200 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
12210 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
12220 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
12230 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
12240 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
12250 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 option takes th
12260 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 ree additional a
12270 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
12280 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 termine the .**
12290 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
122a0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
122b0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 figuration for t
122c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
122d0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 nection]..** ^Th
122e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
122f0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 (the third para
12300 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
12310 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
12320 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
12330 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 o a memory buffe
12340 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f r to use for loo
12350 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a kaside memory..*
12360 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
12370 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 ument after the
12380 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
12390 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a LOOKASIDE verb.*
123a0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e * may be NULL in
123b0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
123c0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
123d0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 the.** lookasid
123e0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 e buffer itself
123f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
12400 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 alloc()]. ^The s
12410 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
12420 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
12430 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
12440 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 buffer slot. ^T
12450 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
12460 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 t is the number
12470 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 of.** slots. Th
12480 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 e size of the bu
12490 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 ffer in the firs
124a0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
124b0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a be greater than.
124c0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 ** or equal to t
124d0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 he product of th
124e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
124f0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 rd arguments. T
12500 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 he buffer.** mus
12510 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
12520 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
12530 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 ry. ^If the sec
12540 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
12550 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ** SQLITE_DBCONF
12560 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 IG_LOOKASIDE is
12570 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f not a multiple o
12580 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 f 8, it is inter
12590 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 nally.** rounded
125a0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 down to the nex
125b0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 t smaller multip
125c0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 le of 8. ^(The
125d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
125e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
125f0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 n for a database
12600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 connection can
12610 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 only be changed
12620 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e when that.** con
12630 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 nection is not c
12640 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c urrently using l
12650 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c ookaside memory,
12660 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 or in other wor
12670 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 ds.** when the "
12680 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 current value" r
12690 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
126a0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
126b0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ](D,[SQLITE_CONF
126c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e IG_LOOKASIDE],..
126d0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 .) is zero..** A
126e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 ny attempt to ch
126f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
12700 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 de memory config
12710 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f uration when loo
12720 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 kaside.** memory
12730 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 is in use leave
12740 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 s the configurat
12750 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e ion unchanged an
12760 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 d returns .** [S
12770 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f QLITE_BUSY].)^</
12780 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
12790 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
127a0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a ABLE_FKEY</dt>.*
127b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
127c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
127d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
127e0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 the enforcement
127f0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 of.** [foreign
12800 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d key constraints]
12810 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 . There should
12820 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
12830 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
12840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
12850 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
12860 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
12870 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 isable FK enforc
12880 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 ement,.** positi
12890 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 ve to enable FK
128a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e enforcement or n
128b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
128c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a FK enforcement.
128d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 ** unchanged. T
128e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
128f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
12900 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 to an integer i
12910 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 nto which.** is
12920 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 written 0 or 1 t
12930 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 o indicate wheth
12940 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e er FK enforcemen
12950 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a t is off or on.*
12960 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
12970 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
12980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
12990 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
129a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
129b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f case the FK enfo
129c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 rcement setting
129d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
129e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
129f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
12a00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
12a10 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 GGER</dt>.** <dd
12a20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
12a30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
12a40 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 or disable [CRE
12a50 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
12a60 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 iggers]..** Ther
12a70 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
12a80 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
12a90 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
12aa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
12ab0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
12ac0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
12ad0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 triggers,.** pos
12ae0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
12af0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 triggers or nega
12b00 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
12b10 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
12b20 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
12b30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
12b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
12b50 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
12b60 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
12b70 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
12b80 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 ate whether trig
12b90 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 gers are disable
12ba0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
12bb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
12bc0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
12bd0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
12be0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
12bf0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
12c00 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 se the trigger s
12c10 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
12c20 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
12c30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
12c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12c50 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
12c60 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 IDE 1001
12c70 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
12c80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
12c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
12ca0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 LE_FKEY 1002
12cb0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f /* int int* */
12cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
12cd0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
12ce0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f TRIGGER 1003 /
12cf0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a * int int* */...
12d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
12d10 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
12d20 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c e Extended Resul
12d30 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 t Codes.**.** ^T
12d40 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
12d50 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
12d60 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
12d70 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
12d80 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
12d90 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
12da0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
12db0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
12dc0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
12dd0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
12de0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
12df0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
12e00 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ity..*/.int sqli
12e10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
12e20 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 ult_codes(sqlite
12e30 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 3*, int onoff);.
12e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12e50 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
12e60 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 id.**.** ^Each e
12e70 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
12e80 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
12e90 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
12ea0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
12eb0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
12ec0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
12ed0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c ^The rowid is al
12ee0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a ways available.*
12ef0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 * as an undeclar
12f00 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 ed column named
12f10 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f ROWID, OID, or _
12f20 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 ROWID_ as long a
12f30 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 s those.** names
12f40 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 are not also us
12f50 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 ed by explicitly
12f60 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
12f70 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 s. ^If.** the ta
12f80 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
12f90 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
12fa0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
12fb0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
12fc0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
12fd0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
12fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 d..**.** ^This r
12ff0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
13000 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
13010 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a e most recent.**
13020 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
13030 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 ERT] into the da
13040 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 tabase from the
13050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13060 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 tion].** in the
13070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 first argument.
13080 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 ^As of SQLite v
13090 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 ersion 3.7.7, th
130a0 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 is routines.** r
130b0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 ecords the last
130c0 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 insert rowid of
130d0 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 both ordinary ta
130e0 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 bles and [virtua
130f0 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 l tables]..** ^I
13100 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 f no successful
13110 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 [INSERT]s.** hav
13120 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 e ever occurred
13130 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 on that database
13140 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 connection, zer
13150 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a o is returned..*
13160 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e *.** ^(If an [IN
13170 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 SERT] occurs wit
13180 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 hin a trigger or
13190 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 within a [virtu
131a0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 al table].** met
131b0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 hod, then this r
131c0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 outine will retu
131d0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f rn the [rowid] o
131e0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a f the inserted.*
131f0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 * row as long as
13200 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 the trigger or
13210 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 virtual table me
13220 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e thod is running.
13230 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
13240 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
13250 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 ual table method
13260 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 ends, the value
13270 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 returned .** by
13280 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
13290 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 verts to what it
132a0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 was before the
132b0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
132c0 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 al.** table meth
132d0 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a od began.)^.**.*
132e0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 * ^An [INSERT] t
132f0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
13300 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
13310 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
13320 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
13330 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 INSERT] and does
13340 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
13350 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
13360 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
13370 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 e. ^Thus INSERT
13380 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 OR FAIL, INSERT
13390 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 OR IGNORE, INSE
133a0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a RT OR ROLLBACK,.
133b0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 ** and INSERT OR
133c0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 ABORT make no c
133d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 hanges to the re
133e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
133f0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 is.** routine wh
13400 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 en their inserti
13410 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 on fails. ^(Whe
13420 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c n INSERT OR REPL
13430 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ACE.** encounter
13440 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 s a constraint v
13450 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 iolation, it doe
13460 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 s not fail. The
13470 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 .** INSERT conti
13480 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
13490 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e on after deletin
134a0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 g rows that caus
134b0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 ed.** the constr
134c0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 aint problem so
134d0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
134e0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 E will always ch
134f0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 ange.** the retu
13500 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
13510 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a interface.)^.**
13520 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 .** ^For the pur
13530 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
13540 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
13550 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
13560 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
13570 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
13580 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
13590 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
135a0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
135b0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 is accessible t
135c0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
135d0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 via the.** [las
135e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
135f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
13600 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
13610 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f ate thread perfo
13620 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 rms a new [INSER
13630 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a T] on the same.*
13640 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
13650 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 ction while the
13660 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
13670 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a sert_rowid()].**
13680 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
13690 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 ning and thus ch
136a0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 anges the last i
136b0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a nsert [rowid],.*
136c0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 * then the value
136d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
136e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
136f0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a t_rowid()] is.**
13700 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
13710 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 nd might not equ
13720 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c al either the ol
13730 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 d or the new.**
13740 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
13750 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f id]..*/.sqlite3_
13760 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 int64 sqlite3_la
13770 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
13780 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
13790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e * CAPI3REF: Coun
137a0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 t The Number Of
137b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
137c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
137d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
137e0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
137f0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 e rows that were
13800 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 changed.** or i
13810 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
13820 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
13830 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
13840 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a d SQL statement.
13850 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ** on the [datab
13860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13870 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
13880 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
13890 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e ..** ^(Only chan
138a0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 ges that are dir
138b0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 ectly specified
138c0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c by the [INSERT],
138d0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 [UPDATE],.** or
138e0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
138f0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e ent are counted.
13900 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e Auxiliary chan
13910 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a ges caused by.**
13920 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f triggers or [fo
13930 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
13940 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 s] are not count
13950 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a ed.)^ Use the.**
13960 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
13970 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
13980 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ion to find the
13990 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
139a0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 changes.** inclu
139b0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 ding changes cau
139c0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 sed by triggers
139d0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 and foreign key
139e0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e actions..**.** ^
139f0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
13a00 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c w that are simul
13a10 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 ated by an [INST
13a20 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a EAD OF trigger].
13a30 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
13a40 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 ed. Only real t
13a50 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 able changes are
13a60 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
13a70 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 ^(A "row change"
13a80 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 is a change to
13a90 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 a single row of
13aa0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a a single table.*
13ab0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 * caused by an I
13ac0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f NSERT, DELETE, o
13ad0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 r UPDATE stateme
13ae0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a nt. Rows that.*
13af0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 * are changed as
13b00 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 side effects of
13b10 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
13b20 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
13b30 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
13b40 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
13b50 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f [DROP TABLE], o
13b60 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a r by any other.*
13b70 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 * mechanisms do
13b80 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 not count as dir
13b90 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e ect row changes.
13ba0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 )^.**.** A "trig
13bb0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 ger context" is
13bc0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 a scope of execu
13bd0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 tion that begins
13be0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 and.** ends wit
13bf0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 h the script of
13c00 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 a [CREATE TRIGGE
13c10 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a R | trigger]. .*
13c20 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 * Most SQL state
13c30 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 ments are.** eva
13c40 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f luated outside o
13c50 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 f any trigger.
13c60 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 This is the "top
13c70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 level".** trigg
13c80 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 er context. If
13c90 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 a trigger fires
13ca0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
13cb0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 el, a.** new tri
13cc0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 gger context is
13cd0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 entered for the
13ce0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 duration of that
13cf0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e one.** trigger.
13d00 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 Subtriggers cr
13d10 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 eate subcontexts
13d20 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 for their durat
13d30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ion..**.** ^Call
13d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 ing [sqlite3_exe
13d50 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
13d60 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 _step()] recursi
13d70 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 vely does.** not
13d80 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 create a new tr
13d90 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
13da0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
13db0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
13dc0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 number of direct
13dd0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 row changes in
13de0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 the.** most rece
13df0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
13e00 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 E, or DELETE sta
13e10 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
13e20 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 e same.** trigge
13e30 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
13e40 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c ^Thus, when cal
13e50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 led from the top
13e60 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e level, this fun
13e70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
13e80 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
13e90 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
13ea0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
13eb0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
13ec0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f ETE.** that also
13ed0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 occurred at the
13ee0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 top level. ^(W
13ef0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
13f00 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 f a trigger,.**
13f10 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
13f20 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 ges() interface
13f30 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f can be called to
13f40 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
13f50 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 of.** changes i
13f60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
13f70 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e tly completed IN
13f80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
13f90 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 DELETE.** state
13fa0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
13fb0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 body of the same
13fc0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 trigger..** How
13fd0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 ever, the number
13fe0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e returned does n
13ff0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
14000 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 es.** caused by
14010 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 subtriggers sinc
14020 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 e those have the
14030 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 ir own context.)
14040 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
14050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
14060 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
14070 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
14080 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
14090 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
140a0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
140b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
140c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
140d0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
140e0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
140f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14100 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
14110 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
14120 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
14130 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
14140 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
14150 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
14160 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
14170 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
14180 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
14190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
141a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
141b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
141c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
141d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
141e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e mber of row chan
141f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 ges caused by [I
14200 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 NSERT],.** [UPDA
14210 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
14220 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 statements since
14230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
14240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f onnection] was o
14250 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 pened..** ^(The
14260 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 count returned b
14270 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
14280 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 changes() includ
14290 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a es all changes.*
142a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 * from all [CREA
142b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
142c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 gger] contexts a
142d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 nd changes made
142e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b by.** [foreign k
142f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 ey actions]. How
14300 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 ever,.** the cou
14310 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
14320 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 ude changes used
14330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 to implement [R
14340 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
14350 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 nts,.** do rollb
14360 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 acks or ABORT pr
14370 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 ocessing, or [DR
14380 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 OP TABLE] proces
14390 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f sing. The.** co
143a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
143b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 lude rows of vie
143c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 ws that fire an
143d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
143e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 ger],.** though
143f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f if the INSTEAD O
14400 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 F trigger makes
14410 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f changes of its o
14420 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 wn, those change
14430 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 s .** are counte
14440 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c d.)^.** ^The sql
14450 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
14460 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f es() function co
14470 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 unts the changes
14480 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 as soon as.** t
14490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
144a0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 t makes them is
144b0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
144c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
144d0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 ndle.** is passe
144e0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
144f0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
14500 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
14510 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
14520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
14530 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
14540 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
14550 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
14560 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
14570 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
14580 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
14590 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
145a0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
145b0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
145c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
145d0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
145e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
145f0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
14600 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
14610 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
14620 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
14630 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
14640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
14650 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
14660 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
14670 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
14680 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
14690 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e ng Query.**.** ^
146a0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
146b0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 uses any pending
146c0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
146d0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 ion to abort and
146e0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 .** return at it
146f0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 s earliest oppor
14700 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 tunity. This rou
14710 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c tine is typicall
14720 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 y.** called in r
14730 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 esponse to a use
14740 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 r action such as
14750 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 pressing "Cance
14760 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 l".** or Ctrl-C
14770 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 where the user w
14780 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 ants a long quer
14790 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 y operation to h
147a0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 alt.** immediate
147b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ly..**.** ^It is
147c0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
147d0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 is routine from
147e0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 a thread differe
147f0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 nt from the.** t
14800 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 hread that is cu
14810 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 rrently running
14820 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 the database ope
14830 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a ration. But it.
14840 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 ** is not safe t
14850 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
14860 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 ine with a [data
14870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14880 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 that.** is clos
14890 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 ed or might clos
148a0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 e before sqlite3
148b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
148c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 urns..**.** ^If
148d0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
148e0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
148f0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
14900 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
14910 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
14920 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
14930 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
14940 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
14950 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
14960 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
14970 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
14980 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e pletion..**.** ^
14990 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
149a0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
149b0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
149c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
149d0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 PT]..** ^If the
149e0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
149f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
14a00 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
14a10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
14a20 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
14a30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
14a40 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
14a50 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
14a60 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
14a70 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
14a80 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cally..**.** ^Th
14a90 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
14aa0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 upt(D) call is i
14ab0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 n effect until a
14ac0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e ll currently run
14ad0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
14ae0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 ements on [datab
14af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
14b00 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e D complete. ^An
14b10 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
14b20 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
14b30 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
14b40 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
14b50 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
14b60 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
14b70 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
14b80 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
14b90 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
14ba0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
14bb0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
14bc0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
14bd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
14be0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 all. ^New SQL s
14bf0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
14c00 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
14c10 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 ter the running
14c20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 statement count
14c30 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
14c40 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 .** not effected
14c50 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
14c60 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 interrupt()..**
14c70 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ^A call to sqlit
14c80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
14c90 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e that occurs when
14ca0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 there are no ru
14cb0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
14cc0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d tements is a no-
14cd0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 op and has no ef
14ce0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
14cf0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
14d00 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
14d10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
14d20 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 errupt() call re
14d30 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 turns..**.** If
14d40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
14d50 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 nection closes w
14d60 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e hile [sqlite3_in
14d70 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 terrupt()].** is
14d80 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 running then ba
14d90 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 d things will li
14da0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a kely happen..*/.
14db0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
14dc0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
14dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14de0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
14df0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
14e00 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
14e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
14e20 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
14e30 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
14e40 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
14e50 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
14e60 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
14e70 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
14e80 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
14e90 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
14ea0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
14eb0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
14ec0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
14ed0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
14ee0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
14ef0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
14f00 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
14f10 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
14f20 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
14f30 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
14f40 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
14f50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
14f60 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
14f70 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
14f80 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
14f90 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
14fa0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
14fb0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
14fc0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
14fd0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
14fe0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
14ff0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
15000 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
15010 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
15020 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
15030 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
15040 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
15050 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
15060 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
15070 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
15080 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
15090 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
150a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
150b0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
150c0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
150d0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
150e0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
150f0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
15100 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
15110 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
15120 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
15130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
15140 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
15150 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
15160 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
15170 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
15180 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
15190 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
151a0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
151b0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
151c0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
151d0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
151e0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
151f0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
15200 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
15210 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
15220 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
15230 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
15240 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
15250 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
15260 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
15270 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
15280 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
15290 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
152a0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
152b0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
152c0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
152d0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
152e0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
152f0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
15300 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
15310 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
15320 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
15330 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
15340 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
15350 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
15360 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
15370 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
15380 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
15390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
153a0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
153b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
153c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
153d0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
153e0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
153f0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
15400 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
15410 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e yte order..*/.in
15420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
15430 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
15440 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
15450 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
15460 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
15470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
15480 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
15490 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
154a0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
154b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
154c0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
154d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
154e0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
154f0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
15500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
15510 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
15520 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
15530 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
15540 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
15550 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
15560 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
15570 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
15580 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
15590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
155a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
155b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
155c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
155d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
155e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
155f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
15600 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
15610 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
15620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
15630 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
15640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
15650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
15660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
15670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
15680 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
15690 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
156a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
156b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
156c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
156d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
156e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
156f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
15700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
15710 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
15720 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
15730 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
15740 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
15750 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
15760 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
15770 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
15780 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
15790 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
157a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
157b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
157c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
157d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
157e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
157f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
15800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
15810 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
15820 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
15830 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
15840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
15850 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
15860 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
15870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
15880 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
15890 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
158a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
158b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
158c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
158d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
158e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
158f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
15900 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
15910 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
15920 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
15930 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
15940 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
15950 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
15960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
15970 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
15980 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
15990 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
159a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
159b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
159c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
159d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
159e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
159f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
15a00 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
15a10 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
15a20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
15a30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
15a40 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
15a50 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
15a60 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
15a70 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
15a80 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
15a90 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
15aa0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
15ab0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
15ac0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
15ad0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
15ae0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
15af0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
15b00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
15b10 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
15b20 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
15b30 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
15b40 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
15b50 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
15b60 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
15b70 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
15b80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
15b90 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
15ba0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
15bb0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
15bc0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
15bd0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
15be0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
15bf0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
15c00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
15c10 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
15c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
15c30 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
15c40 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
15c50 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
15c60 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
15c70 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
15c80 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
15c90 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
15ca0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
15cb0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
15cc0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
15cd0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
15ce0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
15cf0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
15d00 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
15d10 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
15d20 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
15d30 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
15d40 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
15d50 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
15d60 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
15d70 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
15d80 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
15d90 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
15da0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
15db0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
15dc0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
15dd0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
15de0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
15df0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
15e00 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
15e10 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
15e20 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
15e30 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
15e40 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
15e50 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
15e60 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
15e70 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
15e80 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
15e90 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
15ea0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
15eb0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
15ec0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
15ed0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
15ee0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
15ef0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
15f00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
15f10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
15f20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
15f30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
15f40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
15f50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
15f60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
15f70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
15f80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
15f90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
15fa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
15fb0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
15fc0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
15fd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
15fe0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
15ff0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
16000 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
16010 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
16020 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
16030 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
16040 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
16050 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
16060 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
16070 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
16080 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
16090 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
160a0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
160b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
160c0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
160d0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
160e0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
160f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16100 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
16110 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
16120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
16130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
16140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
16150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
16160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
16170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
16180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
161a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
161b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
161c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 sy handler..*/.i
161d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
161e0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
161f0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
16200 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
16210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
16220 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
16230 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
16240 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
16250 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
16260 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
16270 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
16280 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
16290 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
162a0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
162b0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
162c0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
162d0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
162e0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
162f0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
16300 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
16310 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
16320 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
16330 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
16340 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
16350 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
16360 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
16370 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
16380 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
16390 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
163a0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
163b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
163c0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
163d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
163e0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
163f0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
16400 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
16410 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
16420 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
16430 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
16440 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
16450 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
16460 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
16470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16480 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 on] any any give
16490 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
164a0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
164b0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
164c0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
164d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
164e0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
164f0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
16500 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
16510 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
16520 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 cleared.)^.*/.i
16530 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
16540 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
16550 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
16560 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
16570 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
16580 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
16590 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ries.**.** This
165a0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
165b0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
165c0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
165d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
165e0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
165f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
16600 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
16610 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
16620 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
16630 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
16640 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
16650 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
16660 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
16670 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
16680 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
16690 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
166a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
166b0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
166c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
166d0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
166e0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
166f0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
16700 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
16710 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
16720 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
16730 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
16740 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
16750 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
16760 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
16770 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
16780 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
16790 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
167a0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
167b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
167c0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
167d0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
167e0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
167f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
16800 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
16810 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
16820 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
16830 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
16840 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
16850 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
16860 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
16870 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
16880 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
16890 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
168a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
168b0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
168c0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
168d0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
168e0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
168f0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
16900 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
16910 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
16920 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
16930 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
16940 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
16950 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
16960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
16970 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
16980 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
16990 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
169a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
169b0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
169c0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
169d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
169e0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
169f0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
16a00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
16a10 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
16a20 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
16a30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
16a40 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
16a50 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
16a60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
16a70 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
16a80 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
16a90 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
16aa0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
16ab0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
16ac0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
16ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
16ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
16af0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
16b00 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
16b10 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
16b20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
16b30 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
16b40 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
16b50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
16b60 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
16b70 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
16b80 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
16b90 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
16ba0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
16bb0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
16bc0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
16bd0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
16be0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
16bf0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
16c00 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
16c10 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
16c20 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
16c30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
16c40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
16c50 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
16c60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
16c70 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
16c80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
16c90 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
16ca0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
16cb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
16cc0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
16cd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
16ce0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
16cf0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
16d00 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
16d10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
16d20 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
16d30 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
16d40 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
16d50 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
16d60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
16d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
16d80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
16d90 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
16da0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
16db0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
16dc0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
16dd0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
16de0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
16df0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
16e00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
16e10 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
16e20 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
16e30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
16e40 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
16e50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
16e60 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
16e70 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
16e80 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
16e90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
16ea0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
16eb0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
16ec0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
16ed0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
16ee0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
16ef0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
16f00 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
16f10 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
16f20 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
16f30 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
16f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
16f50 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
16f60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
16f70 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
16f80 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
16f90 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
16fa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
16fb0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
16fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
16fd0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
16fe0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
16ff0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
17000 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
17010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
17020 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
17030 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
17040 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
17050 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
17060 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
17070 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
17080 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
17090 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
170a0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
170b0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
170c0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
170d0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
170e0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
170f0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
17100 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
17110 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
17120 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
17130 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
17140 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
17150 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
17160 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
17170 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
17180 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
17190 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
171a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
171b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
171c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e errmsg()]..*/.in
171d0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
171e0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
171f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
17200 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
17210 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
17220 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
17230 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
17240 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
17250 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
17260 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
17270 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
17280 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
17290 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
172a0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
172b0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
172c0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
172d0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
172e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
172f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
17300 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
17310 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
17320 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
17330 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
17340 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
17350 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
17360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
17370 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
17380 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
17390 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
173a0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
173b0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
173c0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
173d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
173e0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
173f0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
17400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
17410 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
17420 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
17430 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
17440 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
17450 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
17460 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
17470 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
17480 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
17490 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
174a0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
174b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
174c0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
174d0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
174e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
174f0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
17500 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
17510 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
17520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
17530 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
17540 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
17550 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
17560 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
17570 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
17580 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
17590 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
175a0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
175b0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
175c0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
175d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
175e0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
175f0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
17600 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
17610 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
17620 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
17630 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
17640 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
17650 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
17660 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
17670 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
17680 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
17690 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
176a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
176b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
176c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
176d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
176e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
176f0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
17700 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
17710 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
17720 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
17730 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
17740 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
17750 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
17760 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
17770 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
17780 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
17790 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
177a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
177b0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
177c0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
177d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
177e0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
177f0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
17800 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
17810 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
17820 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
17830 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
17840 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
17850 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
17860 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
17870 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
17880 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
17890 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
178a0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
178b0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
178c0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
178d0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
178e0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
178f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
17900 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
17910 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
17920 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
17930 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
17940 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
17950 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
17960 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
17970 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
17980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
17990 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
179a0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
179b0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
179c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
179d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
179e0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
179f0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
17a00 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
17a10 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
17a20 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
17a30 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
17a40 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
17a50 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
17a60 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
17a70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
17a80 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
17a90 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
17aa0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
17ab0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
17ac0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 .**.** ^(The %q
17ad0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
17ae0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
17af0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
17b00 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
17b10 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
17b20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
17b30 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
17b40 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
17b50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
17b60 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
17b70 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
17b80 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
17b90 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
17ba0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
17bb0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
17bc0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
17bd0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
17be0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
17bf0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
17c00 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
17c10 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
17c20 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
17c30 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
17c40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
17c50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
17c60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
17c70 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
17c80 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
17c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
17ca0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
17cb0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
17cc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
17cd0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
17ce0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
17cf0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
17d00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
17d10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
17d20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
17d30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
17d40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
17d50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
17d60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
17d70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
17d80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
17d90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
17da0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
17db0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
17dc0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
17dd0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
17de0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
17df0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
17e00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
17e10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
17e20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
17e30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
17e40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
17e50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
17e60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
17e70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
17e80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
17e90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
17ea0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
17eb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
17ec0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
17ed0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
17ee0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
17ef0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
17f00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
17f10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
17f20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
17f30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
17f40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
17f50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
17f60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
17f70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
17f80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
17f90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
17fa0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
17fb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
17fc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
17fd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
17fe0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
17ff0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
18000 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
18010 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
18020 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
18030 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
18040 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
18050 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
18060 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
18070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
18080 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
18090 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
180a0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
180b0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
180c0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
180d0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
180e0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
180f0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
18100 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
18110 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
18120 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
18130 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
18140 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
18150 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
18160 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
18170 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
18180 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
18190 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
181a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
181b0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
181c0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
181d0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
181e0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
181f0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
18200 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
18210 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
18220 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
18230 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
18240 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
18250 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
18260 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
18270 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
18280 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
18290 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
182a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
182b0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
182c0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
182d0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
182e0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 ring.)^.*/.char
182f0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
18300 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
18310 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
18320 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
18330 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
18340 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
18350 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
18360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
18370 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
18380 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 e3_vsnprintf(int
18390 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
183a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f r*, va_list);../
183b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
183c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
183d0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a Subsystem.**.**
183e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
183f0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 uses these thre
18400 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 e routines for a
18410 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a ll of its own.**
18420 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
18430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
18440 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 s. "Core" in the
18450 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
18460 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 ce.** does not i
18470 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 nclude operating
18480 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
18490 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
184a0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e ion. The.** Win
184b0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 dows VFS uses na
184c0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e tive malloc() an
184d0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d d free() for som
184e0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
184f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
18500 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
18510 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
18520 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
18530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
18540 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
18550 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
18560 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
18570 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
18580 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
18590 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
185a0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
185b0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
185c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
185d0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 er. ^If the par
185e0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
185f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
18600 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
18610 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
18620 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
18630 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
18640 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ter..**.** ^Call
18650 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
18660 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 () with a pointe
18670 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 r previously ret
18680 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
18690 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
186a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
186b0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 ) releases that
186c0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 memory so.** tha
186d0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 t it might be re
186e0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 used. ^The sqli
186f0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 te3_free() routi
18700 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 ne is.** a no-op
18710 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 if is called wi
18720 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
18730 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 r. Passing a NU
18740 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f LL pointer.** to
18750 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
18760 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 is harmless. Af
18770 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c ter being freed,
18780 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c memory.** shoul
18790 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 d neither be rea
187a0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 d nor written.
187b0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 Even reading pre
187c0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a viously freed.**
187d0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 memory might re
187e0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e sult in a segmen
187f0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 tation fault or
18800 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
18810 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f or..** Memory co
18820 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d rruption, a segm
18830 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 entation fault,
18840 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
18850 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 error.** might r
18860 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 esult if sqlite3
18870 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 _free() is calle
18880 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c d with a non-NUL
18890 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a L pointer that.*
188a0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e * was not obtain
188b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
188c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
188d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
188e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
188f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 e3_realloc() int
18900 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
18910 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
18920 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
18930 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 cation to be at
18940 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 least N bytes, w
18950 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
18960 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
18970 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 r. The memory a
18980 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
18990 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 resized is the f
189a0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
189b0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 r.)^ ^ If the fi
189c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
189d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
189e0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
189f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
18a00 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
18a10 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
18a20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
18a30 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
18a40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
18a50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
18a60 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
18a70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 ^If the second p
18a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
18a90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 te3_realloc() is
18aa0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
18ab0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
18ac0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
18ad0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
18ae0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
18af0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 _free(P) where P
18b00 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
18b10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
18b20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
18b30 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f ^sqlite3_reallo
18b40 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f c() returns a po
18b50 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
18b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
18b70 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
18b80 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
18b90 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e ULL if sufficien
18ba0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 t memory is unav
18bb0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 ailable..** ^If
18bc0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
18bd0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
18be0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
18bf0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
18c00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
18c10 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
18c20 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
18c30 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
18c40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
18c50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 ite3_realloc() a
18c60 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
18c70 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
18c80 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
18c90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
18ca0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ns NULL, then th
18cb0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
18cc0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 on.** is not fre
18cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ed..**.** ^The m
18ce0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
18cf0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
18d00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
18d10 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
18d20 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
18d30 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
18d40 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
18d50 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
18d60 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
18d70 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
18d80 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
18d90 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
18da0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
18db0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
18dc0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
18dd0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
18de0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
18df0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
18e00 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
18e10 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
18e20 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
18e30 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
18e40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
18e50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
18e60 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
18e70 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
18e80 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
18e90 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
18ea0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
18eb0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
18ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 ..**.** The Wind
18ed0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
18ee0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 layer calls.**
18ef0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
18f00 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 c() and free() d
18f10 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e irectly when con
18f20 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e verting.** filen
18f30 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 ames between the
18f40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
18f50 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a used by SQLite.*
18f60 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 * and whatever f
18f70 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 ilename encoding
18f80 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
18f90 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f particular Windo
18fa0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 ws.** installati
18fb0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f on. Memory allo
18fc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 cation errors ar
18fd0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
18fe0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f ** they are repo
18ff0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
19000 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
19010 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
19020 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
19030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
19040 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 **.** The pointe
19050 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b r arguments to [
19060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
19070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
19080 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 lloc()].** must
19090 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f be either NULL o
190a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 r else pointers
190b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 obtained from a
190c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 prior.** invocat
190d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
190e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
190f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
19100 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f that have.** no
19110 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
19120 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 sed..**.** The a
19130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
19140 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
19150 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a e any part of.**
19160 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
19170 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
19180 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
19190 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
191a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
191b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
191c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
191d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f _malloc(int);.vo
191e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
191f0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
19200 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
19210 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ee(void*);../*.*
19220 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
19230 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 ry Allocator Sta
19240 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 tistics.**.** SQ
19250 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
19260 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
19270 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
19280 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
19290 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
192a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
192b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
192c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
192d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
192e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
192f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
19300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
19310 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e bsystem..**.** ^
19320 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
19330 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 ory_used()] rout
19340 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
19350 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a number of bytes.
19360 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 ** of memory cur
19370 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 rently outstandi
19380 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 ng (malloced but
19390 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 not freed)..**
193a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
193b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
193c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
193d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
193e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
193f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
19400 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 ] since the high
19410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 -water mark.** w
19420 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 as last reset.
19430 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
19440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
19450 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
19460 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
19470 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
19480 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 ()] include any
19490 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 overhead.** adde
194a0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
194b0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
194c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
194d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 lloc()],.** but
194e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 not overhead add
194f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e ed by the any un
19500 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 derlying system
19510 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 library.** routi
19520 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 nes that [sqlite
19530 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 3_malloc()] may
19540 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 call..**.** ^The
19550 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 memory high-wat
19560 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 er mark is reset
19570 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
19580 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c value of.** [sql
19590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
195a0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ()] if and only
195b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
195c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
195d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
195e0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 ()] is true. ^T
195f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
19600 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
19610 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
19620 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 r(1)] is the hig
19630 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
19640 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
19650 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 et..*/.sqlite3_i
19660 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
19670 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
19680 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
19690 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
196a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
196b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
196c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
196d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
196e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
196f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
19700 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
19710 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
19720 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
19730 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
19740 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
19750 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
19760 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
19770 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
19780 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
19790 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
197a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
197b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
197c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
197d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
197e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
197f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
19800 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
19810 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
19820 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
19830 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
19840 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
19850 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
19860 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
19870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
19880 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
19890 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
198a0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ffer P..**.** ^T
198b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
198c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e is routine is in
198d0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e voked (either in
198e0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a ternally or by.*
198f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
19900 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 n) the PRNG is s
19910 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
19920 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a omness obtained.
19930 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ** from the xRan
19940 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
19950 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
19960 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
19970 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 ct..** ^On all s
19980 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
19990 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
199a0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
199b0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
199c0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
199d0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
199e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
199f0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
19a00 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 method..*/.void
19a10 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
19a20 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
19a30 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
19a40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
19a50 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
19a60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
19a70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
19a80 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 egisters an auth
19a90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19aa0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
19ab0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
19ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
19ad0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
19ae0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e t argument..** ^
19af0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
19b00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
19b10 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
19b20 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
19b30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
19b40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
19b50 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
19b60 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
19b70 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
19b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
19b90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
19ba0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
19bb0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a ^At various.**
19bc0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 points during t
19bd0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 he compilation p
19be0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 rocess, as logic
19bf0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 is being create
19c00 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 d.** to perform
19c10 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c various actions,
19c20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
19c30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
19c40 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 ked to.** see if
19c50 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 those actions a
19c60 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 re allowed. ^Th
19c70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
19c80 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
19c90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
19ca0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 K] to allow the
19cb0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f action, [SQLITE_
19cc0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c IGNORE] to disal
19cd0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 low the.** speci
19ce0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 fic action but a
19cf0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 llow the SQL sta
19d00 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e tement to contin
19d10 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ue to be.** comp
19d20 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 iled, or [SQLITE
19d30 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 _DENY] to cause
19d40 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 the entire SQL s
19d50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a tatement to be.*
19d60 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 * rejected with
19d70 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 an error. ^If t
19d80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
19d90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
19da0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
19db0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
19dc0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
19dd0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
19de0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
19df0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
19e00 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
19e10 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
19e20 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
19e30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
19e40 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
19e50 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
19e60 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
19e70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
19e80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
19e90 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
19ea0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
19eb0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 is ok. ^When t
19ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
19ed0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
19ee0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
19ef0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
19f00 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
19f10 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
19f20 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
19f30 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
19f40 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
19f50 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
19f60 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
19f70 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a s denied. .**.**
19f80 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
19f90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
19fa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
19fb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
19fc0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
19fd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
19fe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
19ff0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 er() interface.
1a000 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
1a010 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
1a020 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
1a030 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 nteger [SQLITE_C
1a040 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
1a050 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
1a060 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 s.** the particu
1a070 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 lar action to be
1a080 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 authorized. ^Th
1a090 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
1a0a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
1a0b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1a0c0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 ack are zero-ter
1a0d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1a0e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
1a0f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
1a100 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
1a110 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1a120 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ized..**.** ^If
1a130 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
1a140 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
1a150 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
1a160 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1a170 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
1a180 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
1a190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 ed statement] st
1a1a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 atement is const
1a1b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 ructed to substi
1a1c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 tute.** a NULL v
1a1d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
1a1e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
1a1f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
1a200 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
1a210 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
1a220 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
1a230 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
1a240 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
1a250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
1a260 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
1a270 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
1a280 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
1a290 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
1a2a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 ..** ^If the act
1a2b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
1a2c0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
1a2d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1a2e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
1a2f0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
1a300 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
1a310 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
1a320 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
1a330 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
1a340 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
1a350 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
1a360 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
1a370 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
1a380 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
1a390 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
1a3a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
1a3b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
1a3c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
1a3d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
1a3e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
1a3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1a400 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
1a410 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
1a420 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
1a430 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
1a440 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
1a450 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
1a460 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
1a470 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
1a480 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
1a490 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
1a4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
1a4b0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
1a4c0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
1a4d0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
1a4e0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
1a4f0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
1a500 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
1a510 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
1a520 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
1a530 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
1a540 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
1a550 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
1a560 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
1a570 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
1a580 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
1a590 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
1a5a0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
1a5b0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
1a5c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
1a5d0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
1a5e0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
1a5f0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
1a600 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
1a610 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
1a620 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
1a630 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
1a640 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
1a650 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
1a660 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
1a670 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
1a680 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
1a690 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
1a6a0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
1a6b0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
1a6c0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
1a6d0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
1a6e0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
1a6f0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
1a700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 r..**.** ^(Only
1a710 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
1a720 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
1a730 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
1a740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1a750 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
1a760 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
1a770 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1a780 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
1a790 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 previous call.)
1a7a0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 ^ ^Disable the
1a7b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
1a7c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
1a7d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
1a7e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
1a7f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
1a800 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
1a810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1a820 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
1a830 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
1a840 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
1a850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a860 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1a870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1a880 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
1a890 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
1a8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
1a8b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1a8c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
1a8d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
1a8e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
1a8f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
1a900 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
1a910 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
1a920 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f ^When [sqlite3_
1a930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 prepare_v2()] is
1a940 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 used to prepare
1a950 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 a statement, th
1a960 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d e.** statement m
1a970 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 ight be re-prepa
1a980 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
1a990 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
1a9a0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
1a9b0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
1a9c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1a9d0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
1a9e0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
1a9f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
1aa00 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
1aa10 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
1aa20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1aa30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 )]..**.** ^Note
1aa40 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
1aa50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1aa60 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
1aa70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1aa80 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
1aa90 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
1aaa0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
1aab0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
1aac0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
1aad0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
1aae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
1aaf0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 unless.** as sta
1ab00 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 ted in the previ
1ab10 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 ous paragraph, s
1ab20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
1ab30 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 vokes.** sqlite3
1ab40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f _prepare_v2() to
1ab50 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 reprepare a sta
1ab60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 tement after a s
1ab70 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f chema change..*/
1ab80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 .int sqlite3_set
1ab90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
1aba0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
1abb0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
1abc0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
1abd0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1abe0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1abf0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
1ac00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
1ac10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
1ac20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
1ac30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
1ac40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1ac50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1ac60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1ac70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
1ac80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
1ac90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
1aca0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
1acb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
1acc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
1acd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1ace0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
1acf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
1ad00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
1ad10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1ad20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
1ad30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
1ad40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1ad50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f mation..**.** No
1ad60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 te that SQLITE_I
1ad70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 GNORE is also us
1ad80 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f ed as a [SQLITE_
1ad90 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 ROLLBACK | retur
1ada0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 n code].** from
1adb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 the [sqlite3_vta
1adc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
1add0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
1ade0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1adf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
1ae00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
1ae10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
1ae20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
1ae30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
1ae40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
1ae50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
1ae60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
1ae70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
1ae80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
1ae90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
1aea0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1aeb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1aec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
1aed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
1aee0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
1aef0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
1af00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
1af10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
1af20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
1af30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
1af40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
1af50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1af60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
1af70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
1af80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
1af90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
1afa0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
1afb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
1afc0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
1afd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
1afe0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
1aff0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
1b000 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
1b010 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
1b020 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
1b030 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
1b040 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
1b050 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
1b060 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
1b070 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
1b080 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
1b090 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
1b0a0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
1b0b0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
1b0c0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
1b0d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1b0e0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
1b0f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
1b100 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1b110 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
1b120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
1b130 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
1b140 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
1b150 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
1b160 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
1b170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
1b180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1b190 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
1b1a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
1b1b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
1b1c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
1b1d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
1b1e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
1b1f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
1b200 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
1b210 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
1b220 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
1b230 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
1b240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1b250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1b260 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
1b270 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
1b280 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
1b290 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1b2a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
1b2b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1b2c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1b2d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b2e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1b2f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
1b300 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1b310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b330 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1b340 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
1b350 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1b360 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1b370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b380 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1b390 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
1b3a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1b3b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1b3c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b3d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1b3e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
1b3f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1b400 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1b410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b420 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1b430 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
1b440 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1b450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b470 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
1b480 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
1b490 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1b4a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b4b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b4c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
1b4d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
1b4e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1b4f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b510 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
1b520 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
1b530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1b540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b560 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
1b570 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
1b580 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1b590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1b5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1b5b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
1b5c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
1b5d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1b5e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1b5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1b600 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
1b610 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
1b620 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1b630 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1b640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1b650 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
1b660 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
1b670 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1b680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1b690 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1b6a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
1b6b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
1b6c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1b6d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1b6e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1b6f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
1b700 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
1b710 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1b720 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b730 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1b740 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
1b750 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
1b760 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1b770 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1b780 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
1b790 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
1b7a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1b7b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1b7c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b7d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
1b7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
1b7f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1b800 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b810 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b820 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
1b830 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
1b840 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
1b850 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
1b860 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
1b870 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
1b880 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
1b890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1b8a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
1b8b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b8c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
1b8d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
1b8e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
1b8f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b910 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
1b920 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
1b930 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
1b940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b960 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
1b970 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
1b980 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b990 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
1b9a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b9b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
1b9c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
1b9d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
1b9e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b9f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ba00 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
1ba10 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
1ba20 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
1ba30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1ba40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ba50 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
1ba60 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
1ba70 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
1ba80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1ba90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
1baa0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
1bab0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
1bac0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
1bad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1bae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
1baf0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
1bb00 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
1bb10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1bb20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1bb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1bb40 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
1bb50 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
1bb60 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
1bb70 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1bb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1bb90 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
1bba0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
1bbb0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
1bbc0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
1bbd0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
1bbe0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
1bbf0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
1bc00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
1bc10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
1bc20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
1bc30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
1bc40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
1bc50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
1bc60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
1bc70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
1bc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1bc90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
1bca0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
1bcb0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
1bcc0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
1bcd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
1bce0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1bcf0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 gister callback
1bd00 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 functions that c
1bd10 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a an be used for.*
1bd20 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 * tracing and pr
1bd30 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 ofiling the exec
1bd40 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 ution of SQL sta
1bd50 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
1bd60 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1bd70 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
1bd80 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
1bd90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
1bda0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
1bdb0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
1bdc0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
1bdd0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
1bde0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 3_step()]..** ^T
1bdf0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
1be00 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 () callback is i
1be10 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 nvoked with a UT
1be20 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 F-8 rendering of
1be30 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 the.** SQL stat
1be40 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 ement text as th
1be50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 e statement firs
1be60 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 t begins executi
1be70 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f ng..** ^(Additio
1be80 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 nal sqlite3_trac
1be90 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 e() callbacks mi
1bea0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 ght occur.** as
1beb0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 each triggered s
1bec0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 ubprogram is ent
1bed0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 ered. The callb
1bee0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 acks for trigger
1bef0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 s.** contain a U
1bf00 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 TF-8 SQL comment
1bf10 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 that identifies
1bf20 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a the trigger.)^.
1bf30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
1bf40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1bf50 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
1bf60 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 e3_profile() is
1bf70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 invoked.** as ea
1bf80 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ch SQL statement
1bf90 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 finishes. ^The
1bfa0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1bfb0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 k contains.** th
1bfc0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
1bfd0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e ment text and an
1bfe0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c estimate of wal
1bff0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 l-clock time.**
1c000 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 of how long that
1c010 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 statement took
1c020 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 to run. ^The pr
1c030 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a ofile callback.*
1c040 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 * time is in uni
1c050 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 ts of nanosecond
1c060 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 s, however the c
1c070 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 urrent implement
1c080 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 ation.** is only
1c090 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c capable of mill
1c0a0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 isecond resoluti
1c0b0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 on so the six le
1c0c0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a ast significant.
1c0d0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 ** digits in the
1c0e0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e time are meanin
1c0f0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 gless. Future v
1c100 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1c110 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 e.** might provi
1c120 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c de greater resol
1c130 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f ution on the pro
1c140 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 filer callback.
1c150 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
1c160 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 profile() functi
1c170 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 on is considered
1c180 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e experimental an
1c190 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 d is.** subject
1c1a0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 to change in fut
1c1b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
1c1c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 SQLite..*/.void
1c1d0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
1c1e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 qlite3*, void(*x
1c1f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e Trace)(void*,con
1c200 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a st char*), void*
1c210 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 );.SQLITE_EXPERI
1c220 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c MENTAL void *sql
1c230 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
1c240 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
1c250 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
1c260 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
1c270 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 te3_uint64), voi
1c280 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1c290 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 3REF: Query Prog
1c2a0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a ress Callbacks.*
1c2b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1c2c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
1c2d0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 er(D,N,X,P) inte
1c2e0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 rface causes the
1c2f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
1c300 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e ction X to be in
1c310 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c voked periodical
1c320 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 ly during long r
1c330 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a unning calls to.
1c340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
1c350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
1c360 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ep()] and [sqlit
1c370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
1c380 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 for.** database
1c390 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 connection D. A
1c3a0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f n example use fo
1c3b0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 r this.** interf
1c3c0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 ace is to keep a
1c3d0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 GUI updated dur
1c3e0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 ing a large quer
1c3f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 y..**.** ^The pa
1c400 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 rameter P is pas
1c410 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
1c420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
1c430 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c r to the .** cal
1c440 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
1c450 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 . ^The paramete
1c460 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 r N is the numbe
1c470 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 r of .** [virtua
1c480 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 l machine instru
1c490 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 ctions] that are
1c4a0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 evaluated betwe
1c4b0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a en successive.**
1c4c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
1c4d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a the callback X..
1c4e0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
1c4f0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
1c500 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
1c510 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
1c520 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
1c530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
1c540 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
1c550 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
1c560 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
1c570 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
1c580 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
1c590 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
1c5a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1c5b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
1c5c0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
1c5d0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
1c5e0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
1c5f0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
1c600 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
1c610 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
1c620 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
1c630 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
1c640 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
1c650 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
1c660 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
1c670 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
1c680 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
1c690 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
1c6a0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
1c6b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
1c6c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
1c6d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
1c6e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
1c6f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
1c700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1c710 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1c720 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
1c730 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
1c740 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
1c750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
1c760 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
1c770 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
1c780 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
1c790 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
1c7a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
1c7b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
1c7c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
1c7d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 /.void sqlite3_p
1c7e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1c7f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
1c800 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
1c810 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1c820 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
1c830 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
1c840 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e nnection.**.** ^
1c850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1c860 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
1c870 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
1c880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
1c890 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
1c8a0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
1c8b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
1c8c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
1c8d0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
1c8e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
1c8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1c900 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
1c910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1c920 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
1c930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1c940 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
1c950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
1c960 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
1c970 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
1c980 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
1c990 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
1c9a0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
1c9b0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
1c9c0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
1c9d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
1c9e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
1c9f0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
1ca00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
1ca10 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
1ca20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
1ca30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
1ca40 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
1ca50 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
1ca60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1ca70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
1ca80 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
1ca90 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
1caa0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
1cab0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
1cac0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
1cad0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
1cae0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
1caf0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
1cb00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1cb10 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
1cb20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
1cb30 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
1cb40 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
1cb50 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
1cb60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
1cb70 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
1cb80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
1cb90 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
1cba0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1cbb0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 t encoding for t
1cbc0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c he database will
1cbd0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 be UTF-8 if.**
1cbe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
1cbf0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
1cc00 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 2() is called an
1cc10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 d.** UTF-16 in t
1cc20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
1cc30 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f rder if sqlite3_
1cc40 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 open16() is used
1cc50 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 ..**.** Whether
1cc60 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 or not an error
1cc70 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 occurs when it i
1cc80 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 s opened, resour
1cc90 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ces.** associate
1cca0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
1ccb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1ccc0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 handle should b
1ccd0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a e released by.**
1cce0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
1ccf0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
1cd00 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c when it is no l
1cd10 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a onger required..
1cd20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1cd30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 3_open_v2() inte
1cd40 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
1cd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a sqlite3_open().
1cd60 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
1cd70 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 t accepts two ad
1cd80 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 ditional paramet
1cd90 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ers for addition
1cda0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 al control.** ov
1cdb0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 er the new datab
1cdc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
1cdd0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 ^(The flags par
1cde0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c ameter to.** sql
1cdf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 ite3_open_v2() c
1ce00 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
1ce10 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
1ce20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
1ce30 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
1ce40 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
1ce50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1ce60 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
1ce70 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b EN_FULLMUTEX], [
1ce80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
1ce90 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 EDCACHE],.** [SQ
1cea0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
1ceb0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 ECACHE], and/or
1cec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
1ced0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a ] flags:)^.**.**
1cee0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b <dl>.** ^(<dt>[
1cef0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1cf00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ONLY]</dt>.** <d
1cf10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1cf20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 s opened in read
1cf30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 -only mode. If
1cf40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
1cf50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 s not.** already
1cf60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
1cf70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1cf80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1cf90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1cfa0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a ADWRITE]</dt>.**
1cfb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1cfc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
1cfd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
1cfe0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c ing if possible,
1cff0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f or reading.** o
1d000 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 nly if the file
1d010 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 is write protect
1d020 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 ed by the operat
1d030 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 ing system. In
1d040 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 either.** case t
1d050 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 he database must
1d060 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
1d070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
1d080 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
1d090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
1d0a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1d0b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
1d0c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
1d0d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
1d0e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1d0f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
1d100 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e and writing, an
1d110 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a d is created if.
1d120 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 ** it does not a
1d130 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 lready exist. Th
1d140 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 is is the behavi
1d150 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 or that is alway
1d160 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 s used for.** sq
1d170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
1d180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
1d190 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 ).</dd>)^.** </d
1d1a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 l>.**.** If the
1d1b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
1d1c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1d1d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
1d1e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 the.** combinat
1d1f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
1d200 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
1d210 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a ined with other.
1d220 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1d230 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 READONLY | SQLIT
1d240 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a E_OPEN_* bits].*
1d250 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
1d260 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
1d270 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1d280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1d290 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1d2a0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 t, then the data
1d2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1d2c0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 ** opens in the
1d2d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 multi-thread [th
1d2e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 reading mode] as
1d2f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e long as the sin
1d300 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f gle-thread.** mo
1d310 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 de has not been
1d320 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
1d330 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
1d340 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b e. ^If the.** [
1d350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
1d360 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
1d370 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 et then the data
1d380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1d390 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 opens.** in the
1d3a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
1d3b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 ading mode] unle
1d3c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 ss single-thread
1d3d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
1d3e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 ly selected at c
1d3f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
1d400 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 tart-time..** ^T
1d410 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
1d420 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
1d430 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
1d440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d450 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 to be.** eligib
1d460 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 le to use [share
1d470 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 d cache mode], r
1d480 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
1d490 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
1d4a0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
1d4b0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
1d4c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
1d4d0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e red_cache()]. ^
1d4e0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f The.** [SQLITE_O
1d4f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
1d500 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 ] flag causes th
1d510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1d520 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 ction to not.**
1d530 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b participate in [
1d540 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
1d550 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 e] even if it is
1d560 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
1d570 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
1d580 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1d590 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 _open_v2() is th
1d5a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
1d5b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1d5c0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
1d5d0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
1d5e0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
1d5f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 e that.** the ne
1d600 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
1d610 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ction should use
1d620 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 . ^If the fourt
1d630 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
1d640 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1d650 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
1d660 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1d670 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
1d680 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
1d690 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
1d6a0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
1d6b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
1d6c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
1d6d0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
1d6e0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
1d6f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d ion. ^This in-m
1d700 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
1d710 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
1d720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1d730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
1d740 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
1d750 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1d760 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
1d770 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
1d780 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
1d790 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
1d7a0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
1d7b0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
1d7c0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
1d7d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
1d7e0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
1d7f0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
1d800 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
1d810 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
1d820 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
1d830 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
1d840 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
1d850 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
1d860 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iguity..**.** ^I
1d870 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
1d880 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
1d890 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
1d8a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
1d8b0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
1d8c0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
1d8d0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 . ^This private
1d8e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1d8f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
1d900 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
1d910 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
1d920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1d930 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b closed..**.** [
1d940 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 [URI filenames i
1d950 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 n sqlite3_open()
1d960 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e ]] <h3>URI Filen
1d970 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ames</h3>.**.**
1d980 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d ^If [URI filenam
1d990 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f e] interpretatio
1d9a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e n is enabled, an
1d9b0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 d the filename a
1d9c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e rgument.** begin
1d9d0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 s with "file:",
1d9e0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d then the filenam
1d9f0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 e is interpreted
1da00 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a as a URI. ^URI.
1da10 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 ** filename inte
1da20 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
1da30 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 abled if the [SQ
1da40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
1da50 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e lag is.** set in
1da60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
1da70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
1da80 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 open_v2(), or if
1da90 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 it has.** been
1daa0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 enabled globally
1dab0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
1dac0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f TE_CONFIG_URI] o
1dad0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a ption with the.*
1dae0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
1daf0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 g()] method or b
1db00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 y the [SQLITE_US
1db10 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 E_URI] compile-t
1db20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 ime option..** A
1db30 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
1db40 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 ion 3.7.7, URI f
1db50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
1db60 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 tation is turned
1db70 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 off.** by defau
1db80 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 lt, but future r
1db90 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
1dba0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 e might enable U
1dbb0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 RI filename.** i
1dbc0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 nterpretation by
1dbd0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 default. See "
1dbe0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 [URI filenames]"
1dbf0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
1dc00 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
1dc10 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 **.** URI filena
1dc20 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 mes are parsed a
1dc30 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 ccording to RFC
1dc40 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 3986. ^If the UR
1dc50 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a I contains an.**
1dc60 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e authority, then
1dc70 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 it must be eith
1dc80 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 er an empty stri
1dc90 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 ng or the string
1dca0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 .** "localhost"
1dcb0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 . ^If the author
1dcc0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d ity is not an em
1dcd0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c pty string or "l
1dce0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a ocalhost", an .*
1dcf0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 * error is retur
1dd00 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
1dd10 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 r. ^The fragment
1dd20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
1dd30 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 URI, if .** pres
1dd40 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e ent, is ignored.
1dd50 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
1dd60 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d ses the path com
1dd70 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 ponent of the UR
1dd80 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 I as the name of
1dd90 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a the disk file.*
1dda0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 * which contains
1ddb0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e the database. ^
1ddc0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 If the path begi
1ddd0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 ns with a '/' ch
1dde0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 aracter, .** the
1ddf0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 n it is interpre
1de00 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 ted as an absolu
1de10 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 te path. ^If the
1de20 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 path does not b
1de30 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 egin .** with a
1de40 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 '/' (meaning tha
1de50 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 t the authority
1de60 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 section is omitt
1de70 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 ed from the URI)
1de80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 .** then the pat
1de90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
1dea0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 as a relative p
1deb0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e ath. .** ^On win
1dec0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
1ded0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
1dee0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
1def0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
1df00 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
1df10 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b "C:")..**.** [[
1df20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
1df30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
1df40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
1df50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
1df60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
1df70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
1df80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
1df90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
1dfa0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
1dfb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
1dfc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
1dfd0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 * SQLite interpr
1dfe0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ets the followin
1dff0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 g three query pa
1e000 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 rameters:.**.**
1e010 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c <ul>.** <li> <
1e020 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 b>vfs</b>: ^The
1e030 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 "vfs" parameter
1e040 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 may be used to s
1e050 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 pecify the name
1e060 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 of.** a VFS
1e070 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 object that prov
1e080 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ides the operati
1e090 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
1e0a0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a ace that should.
1e0b0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 ** be used t
1e0c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 o access the dat
1e0d0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 abase file on di
1e0e0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 sk. ^If this opt
1e0f0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a ion is set to.**
1e100 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 an empty st
1e110 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 ring the default
1e120 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 VFS object is u
1e130 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 sed. ^Specifying
1e140 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 an unknown.**
1e150 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 VFS is an err
1e160 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f or. ^If sqlite3_
1e170 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
1e180 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 d and the vfs op
1e190 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 tion is.** p
1e1a0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 resent, then the
1e1b0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 VFS specified b
1e1c0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b y the option tak
1e1d0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 es precedence ov
1e1e0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 er.** the va
1e1f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
1e200 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1e210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
1e220 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 en_v2()..**.**
1e230 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 <li> <b>mode</b
1e240 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 >: ^(The mode pa
1e250 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
1e260 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f et to either "ro
1e270 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 ", "rw" or.**
1e280 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 "rwc". Attempt
1e290 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f ing to set it to
1e2a0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 any other value
1e2b0 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 is an error)^.
1e2c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
1e2d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
1e2e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
1e2f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
1e300 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
1e310 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
1e320 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1e330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
1e340 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
1e350 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
1e360 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
1e370 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 o sqlite3_prepar
1e380 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 e_v2(). ^If the
1e390 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 mode option is s
1e3a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 et to .** "r
1e3b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 w", then the dat
1e3c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1e3d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 for read-write (
1e3e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 but not create)
1e3f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
1e400 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 as if SQLITE_OPE
1e410 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 N_READWRITE (but
1e420 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e not SQLITE_OPEN
1e430 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a _CREATE) had .**
1e440 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e been set. ^
1e450 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 Value "rwc" is e
1e460 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
1e470 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 ting both .**
1e480 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 SQLITE_OPEN_RE
1e490 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 ADWRITE and SQLI
1e4a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 TE_OPEN_CREATE.
1e4b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
1e4c0 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 _v2() is .**
1e4d0 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 used, it is an
1e4e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
1e4f0 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 a value for the
1e500 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
1e510 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 that is .**
1e520 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 less restrictive
1e530 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 than that speci
1e540 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 fied by the flag
1e550 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
1e560 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 third .** pa
1e570 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 rameter..**.**
1e580 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f <li> <b>cache</
1e590 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 b>: ^The cache p
1e5a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
1e5b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 set to either "s
1e5c0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 hared" or.**
1e5d0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 "private". ^Set
1e5e0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 ting it to "shar
1e5f0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e ed" is equivalen
1e600 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 t to setting the
1e610 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
1e620 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
1e630 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 bit in the flags
1e640 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 argument passed
1e650 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 to.** sqlit
1e660 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 e3_open_v2(). ^S
1e670 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 etting the cache
1e680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 parameter to "p
1e690 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 rivate" is .**
1e6a0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f equivalent to
1e6b0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c setting the SQL
1e6c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1e6d0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 CACHE bit..**
1e6e0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 ^If sqlite3_op
1e6f0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
1e700 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 and the "cache"
1e710 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 parameter is pre
1e720 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 sent in.** a
1e730 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 URI filename, i
1e740 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 ts value overrid
1e750 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 es any behaviour
1e760 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 requested by se
1e770 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c tting.** SQL
1e780 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1e790 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f CACHE or SQLITE_
1e7a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
1e7b0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a flag..** </ul>.
1e7c0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e **.** ^Specifyin
1e7d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 g an unknown par
1e7e0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 ameter in the qu
1e7f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
1e800 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e a URI is not an
1e810 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 .** error. Futu
1e820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1e830 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 QLite might unde
1e840 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 rstand additiona
1e850 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d l query.** param
1e860 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 eters. See "[qu
1e870 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 ery parameters w
1e880 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e ith special mean
1e890 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 ing to SQLite]"
1e8a0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
1e8b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
1e8c0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
1e8d0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c ame examples]] <
1e8e0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 h3>URI filename
1e8f0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a examples</h3>.**
1e900 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
1e910 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 r="1" align=cent
1e920 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 er cellpadding=5
1e930 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 >.** <tr><th> UR
1e940 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e I filenames <th>
1e950 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e Results.** <tr>
1e960 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
1e970 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
1e980 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c Open the fil
1e990 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
1e9a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
1e9b0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tory..** <tr><td
1e9c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 > file:/home/fre
1e9d0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a d/data.db<br>.**
1e9e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
1e9f0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 //home/fred/data
1ea00 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 .db <br> .**
1ea10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 file://loc
1ea20 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 alhost/home/fred
1ea30 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 /data.db <br> <t
1ea40 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
1ea50 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 Open the databas
1ea60 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 e file "/home/fr
1ea70 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 ed/data.db"..**
1ea80 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f <tr><td> file://
1ea90 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 darkstar/home/fr
1eaa0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 ed/data.db <td>
1eab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
1eac0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 error. "darkstar
1ead0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 " is not a recog
1eae0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e nized authority.
1eaf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c .** <tr><td styl
1eb00 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e e="white-space:n
1eb10 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 owrap"> .**
1eb20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f file:///C:/
1eb30 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 Documents%20and%
1eb40 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 20Settings/fred/
1eb50 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a Desktop/data.db.
1eb60 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 ** <td> Wind
1eb70 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 ows only: Open t
1eb80 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
1eb90 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b " on fred's desk
1eba0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 top on drive.**
1ebb0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 C:. Not
1ebc0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 e that the %20 e
1ebd0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 scaping in this
1ebe0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 example is not s
1ebf0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 trictly .**
1ec00 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d necessary -
1ec10 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 space character
1ec20 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 s can be used li
1ec30 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 terally.**
1ec40 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e in URI filen
1ec50 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ames..** <tr><td
1ec60 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
1ec70 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 ode=ro&cache=pri
1ec80 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 vate <td> .**
1ec90 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
1eca0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
1ecb0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
1ecc0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ory for read-onl
1ecd0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 y access..**
1ece0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 Regardless
1ecf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
1ed00 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 ot shared-cache
1ed10 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 mode is enabled
1ed20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 by.** d
1ed30 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 efault, use a pr
1ed40 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 ivate cache..**
1ed50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
1ed60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
1ed70 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b ?vfs=unix-nolock
1ed80 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <td>.**
1ed90 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f Open file "/ho
1eda0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 me/fred/data.db"
1edb0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 . Use the specia
1edc0 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f l VFS "unix-nolo
1edd0 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ck"..** <tr><td>
1ede0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
1edf0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e de=readonly <td>
1ee00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
1ee10 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c error. "readonl
1ee20 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 y" is not a vali
1ee30 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 d option for the
1ee40 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 "mode" paramete
1ee50 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a r..** </table>.*
1ee60 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 *.** ^URI hexade
1ee70 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
1ee80 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 uences (%HH) are
1ee90 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 supported withi
1eea0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a n the path and.*
1eeb0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e * query componen
1eec0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 ts of a URI. A h
1eed0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
1eee0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 e sequence consi
1eef0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 sts of a.** perc
1ef00 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d ent sign - "%" -
1ef10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 followed by exa
1ef20 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 ctly two hexadec
1ef30 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 imal digits .**
1ef40 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 specifying an oc
1ef50 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f tet value. ^Befo
1ef60 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 re the path or q
1ef70 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
1ef80 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 of a.** URI file
1ef90 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 name are interpr
1efa0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 eted, they are e
1efb0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 ncoded using UTF
1efc0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 -8 and all .** h
1efd0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
1efe0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c e sequences repl
1eff0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 aced by a single
1f000 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 byte containing
1f010 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f the.** correspo
1f020 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 nding octet. If
1f030 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e this process gen
1f040 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 erates an invali
1f050 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 d UTF-8 encoding
1f060 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 ,.** the results
1f070 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
1f080 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
1f090 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
1f0a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
1f0b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
1f0c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1f0d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
1f0e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
1f0f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
1f100 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
1f110 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
1f120 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
1f130 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
1f140 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
1f150 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
1f160 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
1f170 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
1f180 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
1f190 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
1f1a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
1f1b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
1f1c0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 pen_v2()..*/.int
1f1d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
1f1e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
1f1f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
1f200 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
1f210 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
1f220 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
1f230 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
1f240 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
1f250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
1f260 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
1f270 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
1f280 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
1f290 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
1f2a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
1f2b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
1f2c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
1f2d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
1f2e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
1f2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
1f300 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
1f310 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
1f320 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
1f330 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
1f340 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
1f350 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
1f360 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
1f370 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
1f380 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
1f390 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
1f3a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
1f3b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
1f3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1f3d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
1f3e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
1f3f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ers.**.** This i
1f400 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f 75 74 s a utility rout
1f410 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 ine, useful to V
1f420 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
1f430 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 73 0a ns, that checks.
1f440 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
1f450 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
1f460 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
1f470 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
1f480 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
1f490 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
1f4a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
1f4b0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 e of the query p
1f4c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1f4d0 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 The zFilename ar
1f4e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 66 69 gument is the fi
1f4f0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 lename pointer p
1f500 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
1f510 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Open().** method
1f520 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c 65 6d of a VFS implem
1f530 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a entation. The z
1f540 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74 20 69 Param argument i
1f550 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1f560 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d e.** query param
1f570 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20 20 54 eter we seek. T
1f580 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
1f590 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
1f5a0 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70 the zParam.** p
1f5b0 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 arameter if it e
1f5c0 78 69 73 74 73 2e 20 20 49 66 20 74 68 65 20 70 xists. If the p
1f5d0 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f arameter does no
1f5e0 74 20 65 78 69 73 74 2c 20 74 68 69 73 20 72 6f t exist, this ro
1f5f0 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 utine.** returns
1f600 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1f610 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 .**.** If the zF
1f620 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1f630 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
1f640 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 n is not a point
1f650 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 0a 2a er that SQLite.*
1f660 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 * passed into th
1f670 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65 74 68 e xOpen VFS meth
1f680 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 od, then the beh
1f690 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f avior of this ro
1f6a0 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 utine.** is unde
1f6b0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
1f6c0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ly undesirable..
1f6d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1f6e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
1f6f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 eter(const char
1f700 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 *zFilename, cons
1f710 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b t char *zParam);
1f720 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
1f730 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 F: Error Codes A
1f740 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a nd Messages.**.*
1f750 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
1f760 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
1f770 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
1f780 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
1f790 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
1f7a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
1f7b0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
1f7c0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
1f7d0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
1f7e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
1f7f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
1f800 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
1f810 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
1f820 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
1f830 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
1f840 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
1f850 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
1f860 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
1f870 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
1f880 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 undefined. ^The
1f890 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
1f8a0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 d_errcode().** i
1f8b0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 nterface is the
1f8c0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 same except that
1f8d0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
1f8e0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 ns the .** [exte
1f8f0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
1f900 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 ] even when exte
1f910 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
1f920 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 s are.** disable
1f930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
1f940 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 lite3_errmsg() a
1f950 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 nd sqlite3_errms
1f960 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 g16() return Eng
1f970 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a lish-language.**
1f980 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 text that descr
1f990 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 ibes the error,
1f9a0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
1f9b0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 or UTF-16 respec
1f9c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d tively..** ^(Mem
1f9d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
1f9e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
1f9f0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
1fa00 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 internally..** T
1fa10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
1fa20 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
1fa30 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 worry about free
1fa40 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a ing the result..
1fa50 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
1fa60 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 error string mig
1fa70 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ht be overwritte
1fa80 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
1fa90 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e by.** subsequen
1faa0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 t calls to other
1fab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
1fac0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a e functions.)^.*
1fad0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 *.** When the se
1fae0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
1faf0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 ing mode] is in
1fb00 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 use, it might be
1fb10 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 the.** case tha
1fb20 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 t a second error
1fb30 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 occurs on a sep
1fb40 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 arate thread in
1fb50 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 between.** the t
1fb60 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 ime of the first
1fb70 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 error and the c
1fb80 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 all to these int
1fb90 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e erfaces..** When
1fba0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 that happens, t
1fbb0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 he second error
1fbc0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 will be reported
1fbd0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 since these.**
1fbe0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 interfaces alway
1fbf0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 s report the mos
1fc00 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e t recent result.
1fc10 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 To avoid.** th
1fc20 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 is, each thread
1fc30 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 can obtain exclu
1fc40 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 sive use of the
1fc50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1fc60 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e tion] D.** by in
1fc70 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
1fc80 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 mutex_enter]([sq
1fc90 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
1fca0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e D)) before begin
1fcb0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 ning.** to use D
1fcc0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 and invoking [s
1fcd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
1fce0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f ve]([sqlite3_db_
1fcf0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 mutex](D)) after
1fd00 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f .** all calls to
1fd10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
1fd20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 listed here are
1fd30 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a completed..**.**
1fd40 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 If an interface
1fd50 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 fails with SQLI
1fd60 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 TE_MISUSE, that
1fd70 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 means the interf
1fd80 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b ace.** was invok
1fd90 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 ed incorrectly b
1fda0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
1fdb0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 n. In that case
1fdc0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 , the.** error c
1fdd0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 ode and message
1fde0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 may or may not b
1fdf0 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 e set..*/.int sq
1fe00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
1fe10 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 lite3 *db);.int
1fe20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1fe30 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
1fe40 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 *db);.const cha
1fe50 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
1fe60 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e g(sqlite3*);.con
1fe70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
1fe80 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 _errmsg16(sqlite
1fe90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
1fea0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 3REF: SQL Statem
1feb0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 ent Object.** KE
1fec0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 YWORDS: {prepare
1fed0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 d statement} {pr
1fee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fef0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 s}.**.** An inst
1ff00 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
1ff10 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 ect represents a
1ff20 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
1ff30 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f ement..** This o
1ff40 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 bject is various
1ff50 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 ly known as a "p
1ff60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1ff70 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 t" or a.** "comp
1ff80 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
1ff90 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 nt" or simply as
1ffa0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a a "statement"..
1ffb0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f **.** The life o
1ffc0 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 f a statement ob
1ffd0 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 ject goes someth
1ffe0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ing like this:.*
1fff0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
20000 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a > Create the obj
20010 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
20020 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
20030 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a or a related.**
20040 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a function..
20050 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c ** <li> Bind val
20060 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 ues to [host par
20070 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 ameters] using t
20080 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
20090 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 *().** inte
200a0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 rfaces..** <li>
200b0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 Run the SQL by c
200c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
200d0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d step()] one or m
200e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
200f0 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 i> Reset the sta
20100 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
20110 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
20120 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 hen go back.**
20130 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 to step 2.
20140 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 Do this zero or
20150 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
20160 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 li> Destroy the
20170 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
20180 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
20190 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a ]..** </ol>.**.*
201a0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d * Refer to docum
201b0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 entation on indi
201c0 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 vidual methods a
201d0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f bove for additio
201e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
201f0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 on..*/.typedef s
20200 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 truct sqlite3_st
20210 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b mt sqlite3_stmt;
20220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20230 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 : Run-time Limit
20240 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 s.**.** ^(This i
20250 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 nterface allows
20260 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 the size of vari
20270 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 ous constructs t
20280 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 o be limited.**
20290 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 on a connection
202a0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 by connection ba
202b0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 sis. The first
202c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
202d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
202e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 nnection] whose
202f0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 limit is to be s
20300 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 et or queried.
20310 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
20320 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f rameter is one o
20330 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 f the [limit cat
20340 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 egories] that de
20350 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 fine a.** class
20360 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f of constructs to
20370 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 be size limited
20380 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 . The third par
20390 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
203a0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 new limit for t
203b0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e hat construct.)^
203c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
203d0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 ew limit is a ne
203e0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 gative number, t
203f0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 he limit is unch
20400 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 anged..** ^(For
20410 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 each limit categ
20420 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ory SQLITE_LIMIT
20430 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 _<i>NAME</i> the
20440 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d re is a .** [lim
20450 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 its | hard upper
20460 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 bound].** set a
20470 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 t compile-time b
20480 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 y a C preprocess
20490 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a or macro called.
204a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
204b0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c ITE_MAX_<i>NAME<
204c0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f /i>]..** (The "_
204d0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e LIMIT_" in the n
204e0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 ame is changed t
204f0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a o "_MAX_".))^.**
20500 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e ^Attempts to in
20510 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 crease a limit a
20520 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 bove its hard up
20530 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a per bound are.**
20540 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 silently trunca
20550 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 ted to the hard
20560 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a upper bound..**.
20570 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f ** ^Regardless o
20580 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
20590 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 the limit was c
205a0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 hanged, the .**
205b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
205c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
205d0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 rns the prior va
205e0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
205f0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 ..** ^Hence, to
20600 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 find the current
20610 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 value of a limi
20620 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 t without changi
20630 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 ng it,.** simply
20640 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 invoke this int
20650 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 erface with the
20660 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
20670 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a set to -1..**.**
20680 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 Run-time limits
20690 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
206a0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 r use in applica
206b0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 tions that manag
206c0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 e.** both their
206d0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 own internal dat
206e0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 abase and also d
206f0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 atabases that ar
20700 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 e controlled.**
20710 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 by untrusted ext
20720 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 ernal sources.
20730 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 An example appli
20740 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 cation might be
20750 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 a.** web browser
20760 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
20770 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
20780 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
20790 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
207a0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
207b0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
207c0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
207d0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
207e0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
207f0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
20800 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
20810 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
20820 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
20830 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
20840 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
20850 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
20860 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
20870 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
20880 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
20890 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
208a0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
208b0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
208c0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
208d0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
208e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
208f0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
20900 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
20910 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
20920 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
20930 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
20940 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
20950 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
20960 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
20970 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
20980 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
20990 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
209a0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
209b0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
209c0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
209d0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 e releases..*/.i
209e0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 nt sqlite3_limit
209f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
20a00 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
20a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20a20 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
20a30 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
20a40 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
20a50 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
20a60 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
20a70 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
20a80 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
20a90 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
20aa0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
20ab0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
20ac0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
20ad0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
20ae0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
20af0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
20b00 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
20b10 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
20b20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
20b30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
20b40 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
20b50 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
20b60 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
20b70 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
20b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
20b90 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
20ba0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
20bb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
20bc0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
20bd0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
20be0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
20bf0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
20c00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
20c10 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
20c20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
20c30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
20c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
20c50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
20c60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
20c70 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
20c80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
20c90 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
20ca0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
20cb0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
20cc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
20cd0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
20ce0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
20cf0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
20d00 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
20d10 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
20d20 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
20d30 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
20d40 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
20d50 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
20d60 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
20d70 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
20d80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
20d90 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
20da0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
20db0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
20dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
20dd0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
20de0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
20df0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
20e00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
20e10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
20e20 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
20e30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
20e40 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
20e50 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
20e60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20e70 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
20e80 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
20e90 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
20ea0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
20eb0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
20ec0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
20ed0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
20ee0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
20ef0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
20f00 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
20f10 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
20f20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
20f30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
20f40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
20f50 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f This limit is no
20f60 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 t currently.** e
20f70 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 nforced, though
20f80 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 that might be ad
20f90 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ded in some futu
20fa0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
20fb0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a SQLite.</dd>)^.
20fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
20fd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
20fe0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
20ff0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
21000 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
21010 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
21020 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
21030 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
21040 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
21050 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
21060 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
21070 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
21080 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
21090 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
210a0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
210b0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
210c0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
210d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
210e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
210f0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
21100 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
21110 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
21120 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
21130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
21140 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
21150 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
21160 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
21170 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
21180 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
21190 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
211a0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
211b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
211c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
211d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
211e0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
211f0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
21200 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
21210 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
21220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
21230 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
21240 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
21250 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
21260 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
21270 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
21280 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
21290 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
212a0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f d>)^.** </dl>.*/
212b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
212c0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 LIMIT_LENGTH
212d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
212e0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
212f0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
21300 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
21310 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
21320 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 E_LIMIT_COLUMN
21330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
21340 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
21350 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
21360 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 PTH
21370 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
21380 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
21390 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 ND_SELECT
213a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
213b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
213c0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 OP
213d0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
213e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
213f0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 TION_ARG
21400 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
21410 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
21420 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 ACHED
21430 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
21440 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 SQLITE_LIMIT_LI
21450 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
21460 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e H 8.#defin
21470 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
21480 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 ARIABLE_NUMBER
21490 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
214a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
214b0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 TRIGGER_DEPTH
214c0 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 10../*.
214d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
214e0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
214f0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
21500 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
21510 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
21520 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
21530 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
21540 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
21550 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
21560 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
21570 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
21580 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
21590 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
215a0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
215b0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
215c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
215d0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
215e0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
215f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
21600 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
21610 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
21620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
21630 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
21640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
21650 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
21660 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
21670 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
21680 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
21690 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
216a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
216b0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
216c0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
216d0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
216e0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
216f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21700 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
21710 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
21720 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
21730 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
21740 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
21750 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
21760 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
21770 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
21780 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
21790 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 then zSql is rea
217a0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 d up to the.** f
217b0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
217c0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 ator. ^If nByte
217d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
217e0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 then it is the
217f0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 maximum.** numbe
21800 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 r of bytes read
21810 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 from zSql. ^Wh
21820 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
21830 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
21840 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
21850 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
21860 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
21870 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
21880 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
21890 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
218a0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
218b0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
218c0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
218d0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
218e0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
218f0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
21900 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
21910 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
21920 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
21930 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
21940 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
21950 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
21960 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
21970 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
21980 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
21990 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
219a0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
219b0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 or bytes..**.**
219c0 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f ^If pzTail is no
219d0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 t NULL then *pzT
219e0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ail is made to p
219f0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 oint to the firs
21a00 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 t byte.** past t
21a10 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 he end of the fi
21a20 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e rst SQL statemen
21a30 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 t in zSql. Thes
21a40 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a e routines only.
21a50 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 ** compile the f
21a60 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 irst statement i
21a70 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 n zSql, so *pzTa
21a80 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 il is left point
21a90 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 ing to.** what r
21aa0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 emains uncompile
21ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d d..**.** ^*ppStm
21ac0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
21ad0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
21ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21af0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
21b00 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
21b10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
21b20 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 p()]. ^If there
21b30 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 is an error, *p
21b40 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 pStmt is set.**
21b50 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 to NULL. ^If th
21b60 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e e input text con
21b70 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 tains no SQL (if
21b80 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e the input is an
21b90 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 empty.** string
21ba0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 or a comment) t
21bb0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 hen *ppStmt is s
21bc0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 et to NULL..** T
21bd0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 he calling proce
21be0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 dure is responsi
21bf0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 ble for deleting
21c00 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a the compiled.**
21c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 SQL statement u
21c20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
21c30 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 nalize()] after
21c40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
21c50 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 with it..** ppSt
21c60 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 mt may not be NU
21c70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 LL..**.** ^On su
21c80 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 ccess, the sqlit
21c90 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d e3_prepare() fam
21ca0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 ily of routines
21cb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
21cc0 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 K];.** otherwise
21cd0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
21ce0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
21cf0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
21d00 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
21d10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
21d20 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
21d30 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
21d40 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
21d50 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
21d60 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
21d70 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
21d80 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
21d90 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
21da0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
21db0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
21dc0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 ** ^In the "v2"
21dd0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
21de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
21df0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 nt.** that is re
21e00 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c turned (the [sql
21e10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
21e20 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f t) contains a co
21e30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 py of the.** ori
21e40 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
21e50 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
21e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21e70 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
21e80 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e behave differen
21e90 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 tly in three way
21ea0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
21eb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 <li>.** ^If the
21ec0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
21ed0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 changes, instea
21ee0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b d of returning [
21ef0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 SQLITE_SCHEMA] a
21f00 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 s it.** always u
21f10 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 sed to do, [sqli
21f20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
21f30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
21f40 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c ecompile the SQL
21f50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e .** statement an
21f60 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 d try to run it
21f70 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a again..** </li>.
21f80 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 **.** <li>.** ^W
21f90 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 hen an error occ
21fa0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 urs, [sqlite3_st
21fb0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
21fc0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
21fd0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 ailed.** [error
21fe0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e codes] or [exten
21ff0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d ded error codes]
22000 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 . ^The legacy b
22010 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
22020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
22030 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
22040 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
22050 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
22060 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
22070 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
22080 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f on would have to
22090 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
220a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
220b0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f reset()].** in o
220c0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 rder to find the
220d0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
220e0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
220f0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
22100 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
22110 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
22120 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
22130 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
22140 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
22150 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ly..** </li>.**.
22160 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
22170 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
22180 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 e bound to [para
22190 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 meter | host par
221a0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a ameter] in the .
221b0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ** WHERE clause
221c0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 might influence
221d0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 the choice of qu
221e0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 ery plan for a s
221f0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 tatement,.** the
22200 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
22210 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
22220 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 cally recompiled
22230 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 , as if there ha
22240 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 d been .** a sch
22250 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 ema change, on t
22260 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 he first [sqlit
22270 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
22280 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 following any ch
22290 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ange.** to the [
222a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
222b0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 t | bindings] of
222c0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 that [parameter
222d0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 ]. .** ^The spec
222e0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 ific value of WH
222f0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 ERE-clause [para
22300 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 meter] might inf
22310 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 luence the .** c
22320 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 hoice of query p
22330 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d lan if the param
22340 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 eter is the left
22350 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 -hand side of a
22360 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c [LIKE].** or [GL
22370 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 OB] operator or
22380 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
22390 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 is compared to
223a0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d an indexed colum
223b0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 n.** and the [SQ
223c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 LITE_ENABLE_STAT
223d0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 3] compile-time
223e0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 option is enable
223f0 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f d..** the .** </
22400 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a li>.** </ol>.*/.
22410 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
22420 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
22430 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
22440 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
22450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
22460 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
22470 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
22480 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
22490 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
224a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
224b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
224c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
224d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
224e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
224f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
22500 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
22510 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
22520 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
22530 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
22540 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
22550 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
22560 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
22570 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
22580 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
22590 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
225a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
225b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
225c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
225d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
225e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
225f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
22600 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
22610 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
22620 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
22630 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
22640 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
22650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
22660 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
22670 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
22680 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
22690 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
226a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
226b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
226c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
226d0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
226e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
226f0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
22700 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
22710 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
22720 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
22730 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
22740 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
22750 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
22760 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
22770 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
22780 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
22790 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
227a0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
227b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
227c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
227d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
227e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
227f0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
22800 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
22810 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
22820 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
22830 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
22840 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
22850 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
22860 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
22870 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
22880 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
22890 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
228a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
228b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
228c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
228d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
228e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
228f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
22900 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
22910 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
22920 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
22930 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
22940 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
22950 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e L.**.** ^This in
22960 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
22970 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
22980 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
22990 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
229a0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
229b0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
229c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
229d0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
229e0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
229f0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
22a00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
22a10 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
22a20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
22a30 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
22a40 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c *sqlite3_sql(sql
22a50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
22a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
22a70 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
22a80 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
22a90 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
22aa0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 abase.**.** ^The
22ab0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
22ac0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
22ad0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
22ae0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
22af0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
22b00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
22b10 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
22b20 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
22b30 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
22b40 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
22b50 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
22b60 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
22b70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
22b80 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
22b90 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
22ba0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
22bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
22bc0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
22bd0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
22be0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
22bf0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
22c00 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
22c10 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
22c20 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
22c30 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
22c40 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
22c50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
22c60 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
22c70 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
22c80 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
22c90 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
22ca0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
22cb0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
22cc0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
22cd0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
22ce0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
22cf0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
22d00 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
22d10 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
22d20 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
22d30 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
22d40 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
22d50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
22d60 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
22d70 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
22d80 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
22d90 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
22da0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
22db0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
22dc0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
22dd0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
22de0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
22df0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
22e00 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
22e10 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
22e20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
22e30 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
22e40 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
22e50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
22e60 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
22e70 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
22e80 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
22e90 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
22ea0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
22eb0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
22ec0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
22ed0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
22ee0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
22ef0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
22f00 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
22f10 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
22f20 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
22f30 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
22f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
22f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
22f60 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
22f70 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
22f80 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
22f90 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
22fa0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
22fb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
22fc0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 stmt_readonly(sq
22fd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
22fe0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
22ff0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 REF: Dynamically
23000 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a Typed Value Obj
23010 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
23020 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
23030 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
23040 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
23050 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
23060 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
23070 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
23080 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
23090 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
230a0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
230b0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
230c0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
230d0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
230e0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
230f0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 s it stores. ^V
23100 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 alues stored in
23110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
23120 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 jects.** can be
23130 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 integers, floati
23140 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c ng point values,
23150 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c strings, BLOBs,
23160 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 or NULL..**.**
23170 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 An sqlite3_value
23180 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 object may be e
23190 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 ither "protected
231a0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 " or "unprotecte
231b0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 d"..** Some inte
231c0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 rfaces require a
231d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
231e0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 e3_value. Other
231f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 interfaces.** w
23200 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 ill accept eithe
23210 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 r a protected or
23220 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
23230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
23240 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 * Every interfac
23250 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 e that accepts s
23260 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 qlite3_value arg
23270 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 uments specifies
23280 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e .** whether or n
23290 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 ot it requires a
232a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
232b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 e3_value..**.**
232c0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 The terms "prote
232d0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f cted" and "unpro
232e0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f tected" refer to
232f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a whether or not.
23300 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 ** a mutex is he
23310 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c ld. An internal
23320 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
23330 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
23340 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
23350 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
23360 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
23370 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
23380 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
23390 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
233a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
233b0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
233c0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
233d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
233e0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
233f0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
23400 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
23410 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
23420 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
23430 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
23440 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
23450 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
23460 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
23470 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
23480 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
23490 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
234a0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
234b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
234c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
234d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
234e0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
234f0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
23500 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
23510 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
23520 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
23530 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
23540 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
23550 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
23560 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
23570 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
23580 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
23590 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
235a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 value objects ev
235b0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 en when not stri
235c0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a ctly required..*
235d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
235e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
235f0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 that are passed
23600 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e as parameters in
23610 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d to the.** implem
23620 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 entation of [app
23630 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
23640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 SQL functions]
23650 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a are protected..*
23660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
23670 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 alue object retu
23680 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
23690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
236a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 ()] is unprotect
236b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 ed..** Unprotect
236c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
236d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c objects may onl
236e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a y be used with.*
236f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c * [sqlite3_resul
23700 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b t_value()] and [
23710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
23720 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 ue()]..** The [s
23730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
23740 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 b | sqlite3_valu
23750 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 e_type()] family
23760 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
23770 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 s require protec
23780 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
23790 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 e objects..*/.ty
237a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d pedef struct Mem
237b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
237c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
237d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f SQL Function Co
237e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a ntext Object.**.
237f0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 ** The context i
23800 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 n which an SQL f
23810 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 unction executes
23820 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e is stored in an
23830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 .** sqlite3_cont
23840 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 ext object. ^A
23850 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 pointer to an sq
23860 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
23870 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 ject.** is alway
23880 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
23890 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f r to [applicatio
238a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
238b0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 nctions]..** The
238c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
238d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
238e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
238f0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a will pass this.
23900 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 ** pointer throu
23910 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f gh into calls to
23920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
23930 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 _int | sqlite3_r
23940 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 esult()],.** [sq
23950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
23960 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c context()], [sql
23970 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
23980 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ],.** [sqlite3_c
23990 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
239a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 ()], [sqlite3_ge
239b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a t_auxdata()],.**
239c0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 and/or [sqlite3
239d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e _set_auxdata()].
239e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
239f0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ct sqlite3_conte
23a00 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt sqlite3_conte
23a10 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 xt;../*.** CAPI3
23a20 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c REF: Binding Val
23a30 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 ues To Prepared
23a40 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 Statements.** KE
23a50 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 YWORDS: {host pa
23a60 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 rameter} {host p
23a70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 arameters} {host
23a80 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d parameter name}
23a90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
23aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 QL parameter} {S
23ab0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b QL parameters} {
23ac0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
23ad0 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 g}.**.** ^(In th
23ae0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
23af0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 text input to [s
23b00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
23b10 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
23b20 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
23b30 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
23b40 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
23b50 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 er] that matches
23b60 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e one of followin
23b70 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a g.** templates:.
23b80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
23b90 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
23ba0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 NNN.** <li> :VV
23bb0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a V.** <li> @VVV.
23bc0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
23bd0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
23be0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 the templates ab
23bf0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 ove, NNN represe
23c00 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c nts an integer l
23c10 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 iteral,.** and V
23c20 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e VV represents an
23c30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 alphanumeric id
23c40 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 entifier.)^ ^Th
23c50 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 e values of thes
23c60 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 e.** parameters
23c70 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f (also called "ho
23c80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
23c90 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 es" or "SQL para
23ca0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 meters").** can
23cb0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 be set using the
23cc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
23cd0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e ) routines defin
23ce0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e ed here..**.** ^
23cf0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
23d00 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
23d10 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
23d20 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a nes is always.**
23d30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
23d40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
23d50 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
23d60 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
23d70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
23d80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
23d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
23da0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
23db0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
23dc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
23dd0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 be set..** ^The
23de0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 leftmost SQL pa
23df0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
23e00 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 ndex of 1. ^Whe
23e10 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 n the same named
23e20 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 .** SQL paramete
23e30 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 r is used more t
23e40 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 han once, second
23e50 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a and subsequent.
23e60 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 ** occurrences h
23e70 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 ave the same ind
23e80 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ex as the first
23e90 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e occurrence..** ^
23ea0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 The index for na
23eb0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 med parameters c
23ec0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 an be looked up
23ed0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
23ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
23ef0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 eter_index()] AP
23f00 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e I if desired. ^
23f10 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 The index.** for
23f20 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 "?NNN" paramete
23f30 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 rs is the value
23f40 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 of NNN..** ^The
23f50 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
23f60 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
23f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
23f80 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
23f90 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
23fa0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
23fb0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
23fc0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 : 999)..**.** ^T
23fd0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
23fe0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 t is the value t
23ff0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 o bind to the pa
24000 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e rameter..**.** ^
24010 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e (In those routin
24020 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 es that have a f
24030 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
24040 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 its value is the
24050 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 .** number of by
24060 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d tes in the param
24070 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 eter. To be cle
24080 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 ar: the value is
24090 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
240a0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 f <u>bytes</u> i
240b0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 n the value, not
240c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
240d0 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 haracters.)^.**
240e0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
240f0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 arameter is nega
24100 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 tive, the length
24110 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
24120 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
24130 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 of bytes up to t
24140 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
24150 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 rminator..**.**
24160 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
24170 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
24180 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 ind_blob(), sqli
24190 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
241a0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
241b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 bind_text16() is
241c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 a destructor us
241d0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ed to dispose of
241e0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 the BLOB or.**
241f0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c string after SQL
24200 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 ite has finished
24210 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 with it. ^The
24220 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
24230 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f lled.** to dispo
24240 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
24250 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 r string even if
24260 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c the call to sql
24270 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
24280 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e ,.** sqlite3_bin
24290 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c d_text(), or sql
242a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
242b0 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e () fails. .** ^
242c0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
242d0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
242e0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
242f0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
24300 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
24310 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
24320 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
24330 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
24340 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
24350 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
24360 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 freed..** ^If t
24370 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
24380 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 t has the value
24390 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
243a0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 T], then.** SQLi
243b0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e te makes its own
243c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
243d0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 the data immedi
243e0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a ately, before.**
243f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
24400 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 d_*() routine re
24410 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 turns..**.** ^Th
24420 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
24430 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
24440 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
24450 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
24460 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
24470 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 h zeroes. ^A ze
24480 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
24490 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
244a0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
244b0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
244c0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
244d0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
244e0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
244f0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
24500 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
24510 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
24520 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
24530 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
24540 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
24550 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
24560 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
24570 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
24580 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 nes..** ^A negat
24590 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
245a0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
245b0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
245c0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
245d0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 ^If any of the s
245e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
245f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
24600 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
24610 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 pointer.** for t
24620 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
24630 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 tement] or with
24640 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
24650 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a ment for which.*
24660 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
24670 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
24680 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 ed more recently
24690 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 than [sqlite3_r
246a0 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e eset()],.** then
246b0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 the call will r
246c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 eturn [SQLITE_MI
246d0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 SUSE]. If any s
246e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a qlite3_bind_().*
246f0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 * routine is pas
24700 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 sed a [prepared
24710 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
24720 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
24730 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c ed, the.** resul
24740 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 t is undefined a
24750 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d nd probably harm
24760 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 ful..**.** ^Bind
24770 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
24780 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
24790 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
247a0 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 utine..** ^Unbou
247b0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 nd parameters ar
247c0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
247d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NULL..**.** ^Th
247e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
247f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
24800 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
24810 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a success or an.**
24820 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
24830 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 anything goes w
24840 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 rong..** ^[SQLIT
24850 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
24860 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
24870 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
24880 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
24890 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d ^[SQLITE_NOMEM]
248a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
248b0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
248c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
248d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
248e0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
248f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
24900 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
24910 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
24920 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
24930 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 r_index()]..*/.i
24940 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
24950 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
24960 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
24970 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 oid*, int n, voi
24980 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
24990 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 t sqlite3_bind_d
249a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
249b0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 mt*, int, double
249c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
249d0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f ind_int(sqlite3_
249e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 stmt*, int, int)
249f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
24a00 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
24a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
24a20 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 ite3_int64);.int
24a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 sqlite3_bind_nu
24a40 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ll(sqlite3_stmt*
24a50 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 , int);.int sqli
24a60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 te3_bind_text(sq
24a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
24a80 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
24a90 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
24aa0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
24ab0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
24ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
24ad0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
24ae0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
24af0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
24b00 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 3_bind_value(sql
24b10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
24b20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 const sqlite3_v
24b30 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
24b40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
24b50 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
24b60 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f int, int n);../
24b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
24b80 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
24b90 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 ameters.**.** ^T
24ba0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
24bb0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 be used to find
24bc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 the number of [S
24bd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a QL parameters].*
24be0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 * in a [prepared
24bf0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 statement]. SQ
24c00 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 L parameters are
24c10 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a tokens of the.*
24c20 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e * form "?", "?NN
24c30 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 N", ":AAA", "$AA
24c40 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 A", or "@AAA" th
24c50 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 at serve as.** p
24c60 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
24c70 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 values that are
24c80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
24c90 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 ob | bound].** t
24ca0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 o the parameters
24cb0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 at a later time
24cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
24cd0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
24ce0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
24cf0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
24d00 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
24d10 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
24d20 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
24d30 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
24d40 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
24d50 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
24d60 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
24d70 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
24d80 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 of the ?NNN for
24d90 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 m are used,.** t
24da0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 here may be gaps
24db0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a in the list.)^.
24dc0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
24dd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
24de0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
24df0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
24e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
24e10 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
24e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
24e30 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
24e40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
24e50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
24e60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
24e70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
24e80 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 3REF: Name Of A
24e90 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a Host Parameter.*
24ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
24eb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
24ec0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 _name(P,N) inter
24ed0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
24ee0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
24ef0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 N-th [SQL parame
24f00 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 ter] in the [pre
24f10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
24f20 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 P..** ^(SQL par
24f30 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
24f40 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
24f50 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
24f60 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
24f70 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
24f80 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
24f90 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
24fa0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
24fb0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
24fc0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
24fd0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
24fe0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
24ff0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
25000 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
25010 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a of the name.)^.
25020 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f ** ^Parameters o
25030 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
25040 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
25050 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
25060 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
25070 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 re referred to a
25080 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 s "nameless" or
25090 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d "anonymous param
250a0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eters"..**.** ^T
250b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
250c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
250d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
250e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
250f0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f value N is out o
25100 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
25110 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e N-th parameter
25120 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
25130 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
25140 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 turned. ^The re
25150 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
25160 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
25170 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
25180 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
25190 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
251a0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
251b0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
251c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
251d0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 re16()] or.** [s
251e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
251f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
25200 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
25210 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
25220 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
25230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
25240 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
25250 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
25260 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
25270 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e index()]..*/.con
25280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
25290 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
252a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
252b0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
252c0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
252d0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
252e0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
252f0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 e.**.** ^Return
25300 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
25310 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
25320 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
25330 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
25340 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
25350 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
25360 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
25370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
25380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
25390 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
253a0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
253b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
253c0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
253d0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
253e0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
253f0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
25400 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
25410 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
25420 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
25430 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
25440 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
25450 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
25460 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
25470 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
25480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
25490 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
254a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
254b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
254c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
254d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
254e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
254f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
25500 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
25510 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
25520 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
25530 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
25540 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
25550 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
25560 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
25570 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 .**.** ^Contrary
25580 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f to the intuitio
25590 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 n of many, [sqli
255a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 te3_reset()] doe
255b0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 s not reset.** t
255c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
255d0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 _blob | bindings
255e0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 ] on a [prepared
255f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
25600 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e ^Use this routin
25610 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 e to reset all h
25620 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ost parameters t
25630 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 o NULL..*/.int s
25640 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
25650 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
25660 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
25670 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
25680 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 Columns In A Re
25690 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
256a0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
256b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
256c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 the result set r
256d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
256e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
256f0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f ement]. ^This ro
25700 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
25710 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 if pStmt is an S
25720 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
25730 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 that does not re
25740 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 turn data (for e
25750 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 xample an [UPDAT
25760 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 E])..**.** See a
25770 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 lso: [sqlite3_da
25780 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 ta_count()].*/.i
25790 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
257a0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
257b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
257c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
257d0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
257e0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
257f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
25800 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
25810 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
25820 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
25830 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
25840 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
25850 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
25860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
25870 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
25880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
25890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
258a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
258b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
258c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
258d0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
258e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
258f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
25900 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
25910 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
25920 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
25930 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
25940 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
25950 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
25960 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
25970 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
25980 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
25990 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
259a0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
259b0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
259c0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
259d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
259e0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
259f0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
25a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
25a10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
25a20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
25a30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
25a40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
25a50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
25a60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
25a70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
25a80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
25a90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
25aa0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
25ab0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e * or until the n
25ac0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
25ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
25ae0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
25af0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
25b00 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
25b10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 mn..**.** ^If sq
25b20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
25b30 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
25b40 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
25b50 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
25b60 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
25b70 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
25b80 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
25b90 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
25ba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
25bb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
25bc0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 ^The name of a
25bd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
25be0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
25bf0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f e "AS" clause fo
25c00 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e r.** that column
25c10 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e , if there is an
25c20 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 AS clause. If
25c30 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 there is no AS c
25c40 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 lause.** then th
25c50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
25c60 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 lumn is unspecif
25c70 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e ied and may chan
25c80 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 ge from.** one r
25c90 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
25ca0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
25cb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
25cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
25cd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
25ce0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
25cf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
25d00 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
25d10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
25d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25d30 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
25d40 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
25d50 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 lt.**.** ^These
25d60 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 routines provide
25d70 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 a means to dete
25d80 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 rmine the databa
25d90 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a se, table, and.*
25da0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 * table column t
25db0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 hat is the origi
25dc0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 n of a particula
25dd0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 r result column
25de0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 in.** [SELECT] s
25df0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 tatement..** ^Th
25e00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
25e10 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
25e20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
25e30 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
25e40 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
25e50 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
25e60 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 ^The _database
25e70 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
25e80 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
25e90 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 e name, the _tab
25ea0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 le_ routines ret
25eb0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 urn the table na
25ec0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f me, and.** the o
25ed0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 rigin_ routines
25ee0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d return the colum
25ef0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 n name..** ^The
25f00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
25f10 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
25f20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
25f30 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 tement] is destr
25f40 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 oyed.** using [s
25f50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
25f60 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
25f70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
25f80 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
25f90 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
25fa0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
25fb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
25fc0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
25fd0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
25fe0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
25ff0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
26000 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
26010 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
26020 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e ng..**.** ^The n
26030 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 ames returned ar
26040 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 e the original u
26050 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 n-aliased names
26060 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 of the.** databa
26070 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 se, table, and c
26080 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 olumn..**.** ^Th
26090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
260a0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
260b0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 aces is a [prepa
260c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
260d0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
260e0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
260f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
26100 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
26110 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a mn returned by.*
26120 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c * the statement,
26130 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
26140 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
26150 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
26160 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 e left-most colu
26170 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 mn is column 0 f
26180 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 or these routine
26190 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 s..**.** ^If the
261a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
261b0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
261c0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
261d0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 ession or.** sub
261e0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
261f0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
26200 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
26210 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
26220 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 urn.** NULL. ^T
26230 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
26240 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
26250 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
26260 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
26270 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 .** occurs. ^Ot
26280 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 herwise, they re
26290 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 turn the name of
262a0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 the attached da
262b0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a tabase, table,.*
262c0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 * or column that
262d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f query result co
262e0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 lumn was extract
262f0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e ed from..**.** ^
26300 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
26310 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
26320 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 hose whose names
26330 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 end with "16" r
26340 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 eturn.** UTF-16
26350 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 encoded strings
26360 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 and the other fu
26370 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
26380 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 TF-8..**.** ^The
26390 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 se APIs are only
263a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
263b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
263c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
263d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
263e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 E_COLUMN_METADAT
263f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f A] C-preprocesso
26400 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 r symbol..**.**
26410 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
26420 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
26430 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
26440 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
26450 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
26460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26470 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
26480 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
26490 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
264a0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
264b0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
264c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
264d0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a l one or more.**
264e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
264f0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
26500 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
26510 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
26520 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 for the same [pr
26530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26540 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
26550 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 umn.** at the sa
26560 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
26570 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
26580 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 efined..*/.const
26590 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
265a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
265b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
265c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
265d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
265e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
265f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
26600 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
26610 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
26620 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c n_table_name(sql
26630 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
26640 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
26650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
26660 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
26670 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
26680 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
26690 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
266a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
266b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
266c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
266d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 mn_origin_name16
266e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
266f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
26700 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 3REF: Declared D
26710 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 atatype Of A Que
26720 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 ry Result.**.**
26730 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^(The first para
26740 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 meter is a [prep
26750 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
26760 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 .** If this stat
26770 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 ement is a [SELE
26780 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e CT] statement an
26790 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e d the Nth column
267a0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 of the.** retur
267b0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f ned result set o
267c0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 f that [SELECT]
267d0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d is a table colum
267e0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 n (not an.** exp
267f0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
26800 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 ery) then the de
26810 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 clared type of t
26820 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 he table.** colu
26830 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 mn is returned.)
26840 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ^ ^If the Nth c
26850 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
26860 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a ult set is an.**
26870 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
26880 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 ubquery, then a
26890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
268a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 returned..** ^Th
268b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
268c0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
268d0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 8 encoded..**.**
268e0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
268f0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 given the databa
26900 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a se schema:.**.**
26910 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 CREATE TABLE t1
26920 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a (c1 VARIANT);.**
26930 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c .** and the foll
26940 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 owing statement
26950 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a to be compiled:.
26960 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 **.** SELECT c1
26970 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b + 1, c1 FROM t1;
26980 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 .**.** this rout
26990 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e ine would return
269a0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 the string "VAR
269b0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 IANT" for the se
269c0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 cond result.** c
269d0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e olumn (i==1), an
269e0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
269f0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 for the first r
26a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d esult column (i=
26a10 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 =0).)^.**.** ^SQ
26a20 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
26a30 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e c run-time typin
26a40 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 g. ^So just bec
26a50 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
26a60 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
26a70 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
26a80 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
26a90 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
26aa0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
26ab0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
26ac0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
26ad0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
26ae0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
26af0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
26b00 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
26b10 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 not static. ^Ty
26b20 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
26b30 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
26b40 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
26b50 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
26b60 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
26b70 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
26b80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
26b90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
26ba0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 decltype(sqlite3
26bb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
26bc0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
26bd0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
26be0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
26bf0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
26c00 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 PI3REF: Evaluate
26c10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
26c20 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 t.**.** After a
26c30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26c40 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 ent] has been pr
26c50 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 epared using eit
26c60 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
26c70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
26c80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26c90 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 e16_v2()] or one
26ca0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a of the legacy.*
26cb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 * interfaces [sq
26cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
26cd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
26ce0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 pare16()], this
26cf0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 function.** must
26d00 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f be called one o
26d10 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
26d20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 evaluate the sta
26d30 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 tement..**.** Th
26d40 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
26d50 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 behavior of the
26d60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
26d70 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 interface depend
26d80 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 .** on whether t
26d90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
26da0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
26db0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 the newer "v2" i
26dc0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c nterface.** [sql
26dd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
26de0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
26df0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
26e00 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 or the older leg
26e10 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
26e20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26e30 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
26e40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 3_prepare16()].
26e50 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a The use of the.
26e60 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 ** new "v2" inte
26e70 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 rface is recomme
26e80 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 nded for new app
26e90 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 lications but th
26ea0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
26eb0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 rface will conti
26ec0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 nue to be suppor
26ed0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ted..**.** ^In t
26ee0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
26ef0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
26f00 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
26f10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
26f20 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
26f30 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
26f40 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
26f50 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
26f60 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 ISUSE]..** ^With
26f70 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
26f80 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 ace, any of the
26f90 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f other [result co
26fa0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 des] or.** [exte
26fb0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
26fc0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 s] might be retu
26fd0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a rned as well..**
26fe0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 .** ^[SQLITE_BUS
26ff0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
27000 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
27010 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
27020 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
27030 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
27040 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
27050 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 job. ^If the s
27060 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
27070 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
27080 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
27090 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
270a0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
270b0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
270c0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
270d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
270e0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
270f0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
27100 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 in an.** explici
27110 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
27120 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
27130 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
27140 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
27150 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
27160 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ** ^[SQLITE_DONE
27170 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
27180 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
27190 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
271a0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
271b0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
271c0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
271d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
271e0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
271f0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
27200 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
27210 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
27220 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
27230 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
27240 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
27250 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
27260 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 * ^If the SQL st
27270 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
27280 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
27290 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
272a0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
272b0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
272c0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
272d0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
272e0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
272f0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
27300 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
27310 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
27320 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
27330 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
27340 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
27350 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
27360 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
27370 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
27380 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ta..**.** ^[SQLI
27390 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 TE_ERROR] means
273a0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 that a run-time
273b0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 error (such as a
273c0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 constraint.** v
273d0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 iolation) has oc
273e0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 curred. sqlite3
273f0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
27400 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
27410 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e in on.** the VM.
27420 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f More informatio
27430 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 n may be found b
27440 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
27450 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a e3_errmsg()]..**
27460 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 ^With the legac
27470 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d y interface, a m
27480 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
27490 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 or code (for exa
274a0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 mple,.** [SQLITE
274b0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 _INTERRUPT], [SQ
274c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 LITE_SCHEMA], [S
274d0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 QLITE_CORRUPT],
274e0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a and so forth).**
274f0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
27500 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
27510 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e ite3_reset()] on
27520 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
27530 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e d statement]. ^
27540 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
27550 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f rface,.** the mo
27560 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
27570 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
27580 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 ed directly by s
27590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a qlite3_step()..*
275a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 *.** [SQLITE_MIS
275b0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USE] means that
275c0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 the this routine
275d0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 was called inap
275e0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 propriately..**
275f0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 Perhaps it was c
27600 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 alled on a [prep
27610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
27620 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 that has.** alre
27630 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 ady been [sqlite
27640 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
27650 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e alized] or on on
27660 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 e that had.** pr
27670 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
27680 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d d [SQLITE_ERROR]
27690 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
276a0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a ]. Or it could.
276b0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 ** be the case t
276c0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 hat the same dat
276d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
276e0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 is being used b
276f0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 y two or.** more
27700 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
27710 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 same moment in t
27720 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 ime..**.** For a
27730 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ll versions of S
27740 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 QLite up to and
27750 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 including 3.6.23
27760 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a .1, a call to.**
27770 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
27780 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 )] was required
27790 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 after sqlite3_st
277a0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e ep() returned an
277b0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 ything.** other
277c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
277d0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 ] before any sub
277e0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
277f0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 on of.** sqlite3
27800 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 _step(). Failur
27810 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 e to reset the p
27820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27830 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c t using .** [sql
27840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f ite3_reset()] wo
27850 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e uld result in an
27860 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
27870 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 return from.**
27880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
27890 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 But after versi
278a0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c on 3.6.23.1, sql
278b0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 ite3_step() bega
278c0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 n.** calling [sq
278d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
278e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 utomatically in
278f0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 this circumstanc
27900 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e e rather.** than
27910 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
27920 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 TE_MISUSE]. Thi
27930 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 s is not conside
27940 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c red a compatibil
27950 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 ity.** break bec
27960 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 ause any applica
27970 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 tion that ever r
27980 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 eceives an SQLIT
27990 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a E_MISUSE error.*
279a0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 * is broken by d
279b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 efinition. The
279c0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
279d0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d ORESET] compile-
279e0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 time option.** c
279f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
27a00 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 store the legacy
27a10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
27a20 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 <b>Goofy Interf
27a30 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 ace Alert:</b> I
27a40 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
27a50 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 erface, the sqli
27a60 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 te3_step().** AP
27a70 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 I always returns
27a80 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 a generic error
27a90 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 code, [SQLITE_E
27aa0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 RROR], following
27ab0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 any.** error ot
27ac0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
27ad0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 _BUSY] and [SQLI
27ae0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 TE_MISUSE]. You
27af0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 must call.** [s
27b00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
27b10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
27b20 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 lize()] in order
27b30 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 to find one of
27b40 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
27b50 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 [error codes] th
27b60 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 at better descri
27b70 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a bes the error..*
27b80 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 * We admit that
27b90 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 this is a goofy
27ba0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f design. The pro
27bb0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 blem has been fi
27bc0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 xed.** with the
27bd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 "v2" interface.
27be0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 If you prepare
27bf0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 all of your SQL
27c00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 statements.** us
27c10 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 ing either [sqli
27c20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
27c30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
27c40 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e epare16_v2()] in
27c50 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 stead.** of the
27c60 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f legacy [sqlite3_
27c70 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
27c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
27c90 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 6()] interfaces,
27ca0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 .** then the mor
27cb0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f e specific [erro
27cc0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 r codes] are ret
27cd0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a urned directly.*
27ce0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 * by sqlite3_ste
27cf0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 p(). The use of
27d00 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
27d10 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ace is recommend
27d20 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
27d30 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f e3_step(sqlite3_
27d40 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
27d50 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
27d60 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
27d70 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a result set.**.**
27d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
27d90 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 ta_count(P) inte
27da0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
27db0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
27dc0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 mns in the.** cu
27dd0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
27de0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b result set of [
27df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27e00 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 nt] P..** ^If pr
27e10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27e20 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 P does not have
27e30 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 results ready t
27e40 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 o return.** (via
27e50 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 calls to the [s
27e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
27e70 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t | sqlite3_colu
27e80 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e mn_*()] of.** in
27e90 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 terfaces) then s
27ea0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
27eb0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a t(P) returns 0..
27ec0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
27ed0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
27ee0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 utine also retur
27ef0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e ns 0 if P is a N
27f00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 ULL pointer..**
27f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
27f20 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
27f30 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
27f40 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
27f50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
27f60 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
27f70 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
27f80 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
27f90 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a data_count(P).**
27fa0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e will return non
27fb0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 -zero if previou
27fc0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 s call to [sqlit
27fd0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 e3_step](P) retu
27fe0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
27ff0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 ROW], except in
28000 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 the case of the
28010 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e [PRAGMA incremen
28020 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 tal_vacuum].** w
28030 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 here it always r
28040 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 eturns zero sinc
28050 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 e each step of t
28060 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a hat multi-step.*
28070 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 * pragma returns
28080 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 0 columns of da
28090 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ta..**.** See al
280a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c so: [sqlite3_col
280b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a umn_count()].*/.
280c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 int sqlite3_data
280d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
280e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
280f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
28100 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 ndamental Dataty
28110 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
28120 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a SQLITE_TEXT.**.
28130 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 ** ^(Every value
28140 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f in SQLite has o
28150 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 ne of five funda
28160 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 mental datatypes
28170 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
28180 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e <li> 64-bit sign
28190 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c ed integer.** <l
281a0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 i> 64-bit IEEE f
281b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
281c0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 mber.** <li> str
281d0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 ing.** <li> BLOB
281e0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a .** <li> NULL.**
281f0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
28200 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
28210 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
28220 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
28230 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
28240 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
28250 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
28260 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
28270 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
28280 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
28290 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
282a0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
282b0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
282c0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
282d0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
282e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
282f0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
28300 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
28310 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
28320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
28330 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
28340 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
28350 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
28360 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
28370 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
28380 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
28390 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
283a0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
283b0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
283c0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
283d0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
283e0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
283f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
28400 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
28410 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 From A Query.**
28420 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
28430 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
28440 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
28450 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
28460 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 e "result set" i
28470 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
28480 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
28490 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
284a0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c on about a singl
284b0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
284c0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c current.** resul
284d0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 t row of a query
284e0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 . ^In every cas
284f0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 e the first argu
28500 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
28510 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 r.** to the [pre
28520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
28530 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 that is being e
28540 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 valuated (the [s
28550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a qlite3_stmt*].**
28560 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e that was return
28570 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
28580 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
28590 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 r one of its var
285a0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 iants).** and th
285b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
285c0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
285d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 f the column for
285e0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 which informati
285f0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
28600 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c returned. ^The l
28610 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f eftmost column o
28620 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
28630 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 has the index 0
28640 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 ..** ^The number
28650 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
28660 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 he result can be
28670 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e determined usin
28680 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f g.** [sqlite3_co
28690 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a lumn_count()]..*
286a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
286b0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
286c0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 ot currently poi
286d0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f nt to a valid ro
286e0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 w, or if the.**
286f0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 column index is
28700 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
28710 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 e result is unde
28720 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 fined..** These
28730 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c routines may onl
28740 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e y be called when
28750 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
28760 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
28770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
28780 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
28790 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 E_ROW] and neith
287a0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 er.** [sqlite3_r
287b0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c eset()] nor [sql
287c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
287d0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
287e0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a d subsequently..
287f0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 ** If any of the
28800 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
28810 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
28820 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
28830 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
28840 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 nalize()] or aft
28850 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
28860 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
28870 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 .** something ot
28880 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
28890 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c _ROW], the resul
288a0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
288b0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 ..** If [sqlite3
288c0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
288d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
288e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
288f0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c ze()].** are cal
28900 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 led from a diffe
28910 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c rent thread whil
28920 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
28930 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 outines.** are p
28940 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 ending, then the
28950 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
28960 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
28970 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
28980 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 n_type() routine
28990 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
289a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
289b0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d | datatype code]
289c0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c for the initial
289d0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 data type.** of
289e0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
289f0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e mn. ^The return
28a00 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 ed value is one
28a10 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 of [SQLITE_INTEG
28a20 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ER],.** [SQLITE_
28a30 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f FLOAT], [SQLITE_
28a40 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 TEXT], [SQLITE_B
28a50 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 LOB], or [SQLITE
28a60 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c _NULL]. The val
28a70 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
28a80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
28a90 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
28aa0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
28ab0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 type.** convers
28ac0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 ions have occurr
28ad0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 ed as described
28ae0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 below. After a
28af0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c type conversion,
28b00 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 .** the value re
28b10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
28b20 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
28b30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 is undefined. F
28b40 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
28b50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 s of SQLite may
28b60 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 change the behav
28b70 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 ior of sqlite3_c
28b80 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
28b90 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 following a type
28ba0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a conversion..**.
28bb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
28bc0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
28bd0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e TF-8 string then
28be0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
28bf0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 umn_bytes().** r
28c00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
28c10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
28c20 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
28c30 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
28c40 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
28c50 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c a UTF-16 string,
28c60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
28c70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e lumn_bytes() con
28c80 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
28c90 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 ing to UTF-8 and
28ca0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
28cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
28cc0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 s..** ^If the re
28cd0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
28ce0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
28cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
28d00 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c s() uses.** [sql
28d10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
28d20 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
28d30 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
28d40 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 8 string and ret
28d50 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
28d60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
28d70 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e hat string..** ^
28d80 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
28d90 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 NULL, then sqli
28da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
28db0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e () returns zero.
28dc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 .**.** ^If the r
28dd0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
28de0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
28df0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
28e00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
28e10 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
28e20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
28e30 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
28e40 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 t BLOB or string
28e50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
28e60 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 ult is a UTF-8 s
28e70 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 tring, then sqli
28e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
28e90 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 16() converts.**
28ea0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
28eb0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 TF-16 and then r
28ec0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
28ed0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
28ee0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
28ef0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
28f00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
28f10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 lumn_bytes16() u
28f20 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
28f30 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
28f40 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
28f50 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 e to a UTF-16 st
28f60 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
28f70 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
28f80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
28f90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
28fa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c he result is NUL
28fb0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f L, then sqlite3_
28fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
28fd0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
28fe0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 *.** ^The values
28ff0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
29000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
29010 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 es()] and .** [s
29020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
29030 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 tes16()] do not
29040 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f include the zero
29050 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 terminators at
29060 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 the end.** of th
29070 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 e string. ^For
29080 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c clarity: the val
29090 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a ues returned by.
290a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
290b0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 mn_bytes()] and
290c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
290d0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 bytes16()] are t
290e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
290f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 bytes in the str
29100 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d ing, not the num
29110 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
29120 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 s..**.** ^String
29130 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 s returned by sq
29140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
29150 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
29160 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c column_text16(),
29170 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 .** even empty s
29180 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 trings, are alwa
29190 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 ys zero terminat
291a0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e ed. ^The return
291b0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 .** value from s
291c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
291d0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d ob() for a zero-
291e0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 length BLOB is a
291f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
29200 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 *.** ^The object
29210 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
29220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
29230 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b ue()] is an.** [
29240 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
29250 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
29260 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 t. An unprotect
29270 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29280 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f object.** may o
29290 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
292a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
292b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
292c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
292d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 e()]..** If the
292e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
292f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
29300 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
29310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
29320 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 n_value()] is us
29330 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 ed in any other
29340 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 way, including c
29350 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 alls.** to routi
29360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
29370 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 3_value_int()],
29380 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
29390 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
293a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
293b0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 es()], then the
293c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
293d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fined..**.** The
293e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 se routines atte
293f0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 mpt to convert t
29400 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 he value where a
29410 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f ppropriate. ^Fo
29420 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
29430 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
29440 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
29450 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
29460 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
29470 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
29480 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
29490 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
294a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
294b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
294c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 tomatically. ^(
294d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
294e0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
294f0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
29500 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
29510 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
29520 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
29530 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
29540 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
29550 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
29560 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
29570 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
29580 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
29590 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
295a0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
295b0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
295c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
295d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
295e0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
295f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
29600 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
29610 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
29620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
29630 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
29640 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
29650 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
29660 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
29670 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
29680 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
29690 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
296a0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
296b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
296c0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
296d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
296e0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
296f0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
29700 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
29710 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
29720 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e <td> Same as IN
29730 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c TEGER->TEXT.** <
29740 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
29750 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
29760 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
29770 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 m float to integ
29780 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
29790 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 FLOAT <td> T
297a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
297b0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
297c0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e he float.** <tr>
297d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
297e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
297f0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d > Same as FLOAT-
29800 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
29810 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
29820 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 INTEGER <td> U
29830 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
29840 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
29850 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
29860 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a d> Use atof().**
29870 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
29880 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
29890 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
298a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
298b0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
298c0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
298d0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 t to TEXT then u
298e0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
298f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
29900 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
29910 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
29920 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 XT then use atof
29930 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
29940 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 BLOB <td> T
29950 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 EXT <td> Add
29960 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f a zero terminato
29970 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c r if needed.** <
29980 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
29990 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
299a0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 The table above
299b0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 makes reference
299c0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c to standard C l
299d0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 ibrary functions
299e0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 atoi().** and a
299f0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 tof(). SQLite d
29a00 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 oes not really u
29a10 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f se these functio
29a20 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a ns. It has its.
29a30 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e ** own equivalen
29a40 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 t internal routi
29a50 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 nes. The atoi()
29a60 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 and atof() name
29a70 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e s are.** used in
29a80 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 the table for b
29a90 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 revity and becau
29aa0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 se they are fami
29ab0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 liar to most.**
29ac0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a C programmers..*
29ad0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
29ae0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
29af0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
29b00 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
29b10 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
29b20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
29b30 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
29b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
29b50 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
29b60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
29b70 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
29b80 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 dated..** Type c
29b90 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 onversions and p
29ba0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 ointer invalidat
29bb0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 ions might occur
29bc0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f .** in the follo
29bd0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a wing cases:.**.*
29be0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
29bf0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
29c00 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
29c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29c20 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 text() or.**
29c30 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
29c40 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
29c50 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
29c60 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
29c70 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 need to be
29c80 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 added to the st
29c90 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c ring.</li>.** <l
29ca0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
29cb0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 ontent is UTF-8
29cc0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
29cd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
29ce0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
29cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
29d00 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
29d10 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
29d20 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
29d30 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 * to UTF-16
29d40 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
29d50 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
29d60 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 nt is UTF-16 tex
29d70 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
29d80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
29d90 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
29da0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
29db0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
29dc0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
29dd0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
29de0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a to UTF-8.</li>.*
29df0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 * </ul>.**.** ^C
29e00 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
29e10 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 en UTF-16be and
29e20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 UTF-16le are alw
29e30 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 ays done in plac
29e40 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 e and do.** not
29e50 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 invalidate a pri
29e60 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 or pointer, thou
29e70 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 gh of course the
29e80 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
29e90 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 buffer.** that t
29ea0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 he prior pointer
29eb0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c references will
29ec0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 have been modif
29ed0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 ied. Other kind
29ee0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 s.** of conversi
29ef0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 on are done in p
29f00 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 lace when it is
29f10 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f possible, but so
29f20 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 metimes they.**
29f30 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 are not possible
29f40 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 and in those ca
29f50 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 ses prior pointe
29f60 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 rs are invalidat
29f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 ed..**.** The sa
29f80 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 fest and easiest
29f90 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c to remember pol
29fa0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 icy is to invoke
29fb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
29fc0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 ** in one of the
29fd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a following ways:
29fe0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
29ff0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
2a000 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 mn_text() follow
2a010 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2a020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
2a030 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
2a040 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
2a050 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
2a060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2a070 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
2a080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a090 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 ext16() followed
2a0a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2a0b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 mn_bytes16()</li
2a0c0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
2a0d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
2a0e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c you should call
2a0f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a100 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 text(),.** sqlit
2a110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2a120 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c , or sqlite3_col
2a130 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 umn_text16() fir
2a140 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 st to force the
2a150 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 result.** into t
2a160 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 he desired forma
2a170 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 t, then invoke s
2a180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2a190 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 tes() or.** sqli
2a1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2a1b0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 16() to find the
2a1c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 size of the res
2a1d0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 ult. Do not mix
2a1e0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c calls.** to sql
2a1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2a200 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
2a210 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 lumn_blob() with
2a220 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
2a230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2a240 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f s16(), and do no
2a250 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 t mix calls to s
2a260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2a270 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 xt16().** with c
2a280 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2a290 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a column_bytes()..
2a2a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 **.** ^The point
2a2b0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 ers returned are
2a2c0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 valid until a t
2a2d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f ype conversion o
2a2e0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 ccurs as.** desc
2a2f0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 ribed above, or
2a300 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 until [sqlite3_s
2a310 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
2a320 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2a330 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2a340 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ize()] is called
2a350 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 . ^The memory s
2a360 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c pace used to hol
2a370 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 d strings.** and
2a380 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 BLOBs is freed
2a390 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
2a3a0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 Do <b>not</b> pa
2a3b0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 ss the pointers
2a3c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c returned.** [sql
2a3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2a3e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f ()], [sqlite3_co
2a3f0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 lumn_text()], et
2a400 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 c. into.** [sqli
2a410 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a te3_free()]..**.
2a420 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 ** ^(If a memory
2a430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
2a440 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
2a450 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f the evaluation o
2a460 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 f any.** of thes
2a470 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 e routines, a de
2a480 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 fault value is r
2a490 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 eturned. The de
2a4a0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 fault value.** i
2a4b0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 s either the int
2a4c0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 eger 0, the floa
2a4d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2a4e0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c r 0.0, or a NULL
2a4f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 .** pointer. Su
2a500 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
2a510 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
2a520 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 de()] will retur
2a530 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d n.** [SQLITE_NOM
2a540 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 EM].)^.*/.const
2a550 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2a560 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
2a570 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a580 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2a590 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
2a5a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2a5b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
2a5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2a5d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2a5e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 int iCol);.doub
2a5f0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d le sqlite3_colum
2a600 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
2a610 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2a620 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2a630 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
2a640 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a650 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 l);.sqlite3_int6
2a660 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
2a670 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2a680 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2a690 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
2a6a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2a6b0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
2a6c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a6d0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a l);.const void *
2a6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a6f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
2a700 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2a710 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2a720 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
2a730 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2a740 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 ;.sqlite3_value
2a750 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a760 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
2a770 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2a780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2a790 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
2a7a0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
2a7b0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ject.**.** ^The
2a7c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2a7d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
2a7e0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 alled to delete
2a7f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2a800 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 ement]..** ^If t
2a810 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
2a820 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 valuation of the
2a830 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 statement encou
2a840 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 ntered no errors
2a850 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 .** or if the st
2a860 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 atement is never
2a870 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c been evaluated,
2a880 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 then sqlite3_fi
2a890 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 nalize() returns
2a8a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 .** SQLITE_OK.
2a8b0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
2a8c0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f ent evaluation o
2a8d0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 f statement S fa
2a8e0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 iled, then.** sq
2a8f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
2a900 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 ) returns the ap
2a910 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
2a920 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 code] or.** [ex
2a930 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
2a940 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 e]..**.** ^The s
2a950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2a960 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 S) routine can b
2a970 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
2a980 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 point during.**
2a990 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f the life cycle o
2a9a0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
2a9b0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 ement] S:.** bef
2a9c0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 ore statement S
2a9d0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 is ever evaluate
2a9e0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 d, after.** one
2a9f0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f or more calls to
2aa00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2aa10 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 )], or after any
2aa20 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c call.** to [sql
2aa30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 ite3_step()] reg
2aa40 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
2aa50 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 er or not the st
2aa60 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 atement has.** c
2aa70 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
2aa80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b on..**.** ^Invok
2aa90 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 ing sqlite3_fina
2aaa0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c lize() on a NULL
2aab0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 pointer is a ha
2aac0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a rmless no-op..**
2aad0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
2aae0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a ion must finaliz
2aaf0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 e every [prepare
2ab00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
2ab10 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a order to avoid.*
2ab20 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 * resource leaks
2ab30 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 . It is a griev
2ab40 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 ous error for th
2ab50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f e application to
2ab60 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 try to use.** a
2ab70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2ab80 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
2ab90 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e been finalized.
2aba0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 Any use of a p
2abb0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
2abc0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2abd0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2abe0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 can result in u
2abf0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 ndefined and.**
2ac00 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
2ac10 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 vior such as seg
2ac20 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 faults and heap
2ac30 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 corruption..*/.i
2ac40 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
2ac50 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
2ac60 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2ac70 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
2ac80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
2ac90 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a ement Object.**.
2aca0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
2acb0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
2acc0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
2acd0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
2ace0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
2acf0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
2ad00 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
2ad10 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
2ad20 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 ecuted..** ^Any
2ad30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
2ad40 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
2ad50 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
2ad60 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
2ad70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
2ad80 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
2ad90 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
2ada0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
2adb0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
2adc0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
2add0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
2ade0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
2adf0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
2ae00 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
2ae10 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
2ae20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ae30 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f nt] S.** back to
2ae40 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
2ae50 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
2ae60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
2ae70 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2ae80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2ae90 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
2aea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2aeb0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 t] S returned [S
2aec0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 QLITE_ROW] or [S
2aed0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 QLITE_DONE],.**
2aee0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
2aef0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
2af00 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
2af10 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 lled on S,.** th
2af20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
2af30 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
2af40 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
2af50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
2af60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
2af70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
2af80 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
2af90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2afa0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
2afb0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 ror, then.** [sq
2afc0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2afd0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
2afe0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
2aff0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
2b000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2b010 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
2b020 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2b030 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e values.** of an
2b040 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
2b050 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
2b060 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
2b070 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
2b080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
2b090 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
2b0a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2b0b0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
2b0c0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
2b0d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 Functions.** KE
2b0e0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f YWORDS: {functio
2b0f0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
2b100 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 nes}.** KEYWORDS
2b110 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
2b120 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2b130 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ion}.** KEYWORDS
2b140 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
2b150 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2b160 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions}.**.** ^The
2b170 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f se functions (co
2b180 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e llectively known
2b190 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 as "function cr
2b1a0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 eation routines"
2b1b0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f ).** are used to
2b1c0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f add SQL functio
2b1d0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
2b1e0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 or to redefine
2b1f0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
2b200 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 of existing SQL
2b210 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
2b220 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e regates. The on
2b230 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 ly differences b
2b240 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 etween.** these
2b250 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 routines are the
2b260 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 text encoding e
2b270 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 xpected for.** t
2b280 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2b290 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 ter (the name of
2b2a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 the function be
2b2b0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 ing created).**
2b2c0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 and the presence
2b2d0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 or absence of a
2b2e0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c destructor call
2b2f0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 back for.** the
2b300 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
2b310 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
2b320 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
2b330 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 eter is the [dat
2b340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b350 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 ] to which the S
2b360 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 QL.** function i
2b370 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 s to be added.
2b380 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 ^If an applicati
2b390 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 on uses more tha
2b3a0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a n one database.*
2b3b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 * connection the
2b3c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
2b3d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2b3e0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 ons must be adde
2b3f0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 d.** to each dat
2b400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b410 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a separately..**.
2b420 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 ** ^The second p
2b430 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2b440 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 name of the SQL
2b450 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 function to be c
2b460 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 reated or.** red
2b470 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 efined. ^The le
2b480 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 ngth of the name
2b490 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 is limited to 2
2b4a0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 55 bytes in a UT
2b4b0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 F-8.** represent
2b4c0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 ation, exclusive
2b4d0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 of the zero-ter
2b4e0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 minator. ^Note
2b4f0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a that the name.**
2b500 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 length limit is
2b510 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c in UTF-8 bytes,
2b520 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 not characters
2b530 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 nor UTF-16 bytes
2b540 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 . .** ^Any atte
2b550 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 mpt to create a
2b560 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
2b570 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 longer name.** w
2b580 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 ill result in [S
2b590 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 QLITE_MISUSE] be
2b5a0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a ing returned..**
2b5b0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 .** ^The third p
2b5c0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a arameter (nArg).
2b5d0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ** is the number
2b5e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 of arguments th
2b5f0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 at the SQL funct
2b600 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
2b610 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 ate takes. ^If t
2b620 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
2b630 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 -1, then the SQ
2b640 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
2b650 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 aggregate may t
2b660 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f ake any number o
2b670 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 f arguments betw
2b680 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 een 0 and the li
2b690 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 mit.** set by [s
2b6a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 qlite3_limit]([S
2b6b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
2b6c0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 TION_ARG]). If
2b6d0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
2b6e0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 ameter is less t
2b6f0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 han -1 or greate
2b700 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 r than 127 then
2b710 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a the behavior is.
2b720 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
2b730 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
2b740 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 parameter, eText
2b750 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 Rep, specifies w
2b760 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 hat.** [SQLITE_U
2b770 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 TF8 | text encod
2b780 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 ing] this SQL fu
2b790 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 nction prefers f
2b7a0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 or.** its parame
2b7b0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c ters. Every SQL
2b7c0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
2b7d0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 entation must be
2b7e0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a able to work.**
2b7f0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 with UTF-8, UTF
2b800 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 -16le, or UTF-16
2b810 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d be. But some im
2b820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
2b830 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 y be.** more eff
2b840 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 icient with one
2b850 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e encoding than an
2b860 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c other. ^An appl
2b870 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 ication may.** i
2b880 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 nvoke sqlite3_cr
2b890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 eate_function()
2b8a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
2b8b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d e_function16() m
2b8c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 ultiple.** times
2b8d0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 with the same f
2b8e0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 unction but with
2b8f0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 different value
2b900 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a s of eTextRep..*
2b910 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 * ^When multiple
2b920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
2b930 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
2b940 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 ction are availa
2b950 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 ble, SQLite.** w
2b960 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 ill pick the one
2b970 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 that involves t
2b980 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
2b990 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 of data conversi
2b9a0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 on..** If there
2b9b0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 is only a single
2b9c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2b9d0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 which does not c
2b9e0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a are what text.**
2b9f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
2ba00 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 d, then the four
2ba10 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 th argument shou
2ba20 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e ld be [SQLITE_AN
2ba30 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 Y]..**.** ^(The
2ba40 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
2ba50 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
2ba60 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d pointer. The im
2ba70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2ba80 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
2ba90 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 can gain access
2baa0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 to this pointer
2bab0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 using [sqlite3_u
2bac0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a ser_data()].)^.*
2bad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c *.** ^The sixth,
2bae0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 seventh and eig
2baf0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 hth parameters,
2bb00 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
2bb10 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
2bb20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
2bb30 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
2bb40 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
2bb50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2bb60 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2bb70 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 . ^A scalar SQL
2bb80 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
2bb90 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
2bba0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 ion of the xFunc
2bbb0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c .** callback onl
2bbc0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 y; NULL pointers
2bbd0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
2bbe0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 as the xStep and
2bbf0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d xFinal.** param
2bc00 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 eters. ^An aggre
2bc10 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
2bc20 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
2bc30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2bc40 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
2bc50 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 nal and NULL poi
2bc60 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 nter must be pas
2bc70 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e sed for xFunc. ^
2bc80 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 To delete an exi
2bc90 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e sting.** SQL fun
2bca0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
2bcb0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f te, pass NULL po
2bcc0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 inters for all t
2bcd0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a hree function.**
2bce0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a callbacks..**.*
2bcf0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 * ^(If the ninth
2bd00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
2bd10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2bd20 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f ction_v2() is no
2bd30 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 t NULL,.** then
2bd40 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 it is destructor
2bd50 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 for the applica
2bd60 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
2bd70 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 r. .** The destr
2bd80 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 uctor is invoked
2bd90 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 when the functi
2bda0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 on is deleted, e
2bdb0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a ither by being.*
2bdc0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 * overloaded or
2bdd0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
2bde0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
2bdf0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 ses.)^.** ^The d
2be00 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 estructor is als
2be10 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 o invoked if the
2be20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
2be30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2be40 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a ion_v2() fails..
2be50 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 ** ^When the des
2be60 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b tructor callback
2be70 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 of the tenth pa
2be80 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b rameter is invok
2be90 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 ed, it.** is pas
2bea0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 sed a single arg
2beb0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
2bec0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 copy of the app
2bed0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a lication data .*
2bee0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 * pointer which
2bef0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 was the fifth pa
2bf00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2bf10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2bf20 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e on_v2()..**.** ^
2bf30 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 It is permitted
2bf40 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 to register mult
2bf50 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
2bf60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
2bf70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 .** functions wi
2bf80 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 th the same name
2bf90 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 but with either
2bfa0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 differing numbe
2bfb0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e rs of.** argumen
2bfc0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 ts or differing
2bfd0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
2bfe0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 ncodings. ^SQLi
2bff0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 te will use.** t
2c000 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2c010 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 n that most clos
2c020 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 ely matches the
2c030 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 way in which the
2c040 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
2c050 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 is used. ^A fu
2c060 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
2c070 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
2c080 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 -negative.** nAr
2c090 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 g parameter is a
2c0a0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 better match th
2c0b0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d an a function im
2c0c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
2c0d0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 h.** a negative
2c0e0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 nArg. ^A functi
2c0f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 on where the pre
2c100 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
2c110 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 ding.** matches
2c120 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 the database enc
2c130 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 oding is a bette
2c140 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 r.** match than
2c150 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
2c160 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 the encoding is
2c170 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a different. .**
2c180 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
2c190 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
2c1a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 difference is be
2c1b0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e tween UTF16le an
2c1c0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 d UTF16be.** is
2c1d0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 a closer match t
2c1e0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
2c1f0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
2c200 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a g difference is.
2c210 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 ** between UTF8
2c220 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a and UTF16..**.**
2c230 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 ^Built-in funct
2c240 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 ions may be over
2c250 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 loaded by new ap
2c260 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2c270 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a d functions..**.
2c280 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 ** ^An applicati
2c290 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2c2a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
2c2b0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a to call other.*
2c2c0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
2c2d0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 ces. However, s
2c2e0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e uch calls must n
2c2f0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 ot.** close the
2c300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c310 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 ion nor finalize
2c320 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 or reset the pr
2c330 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
2c340 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 ent in which the
2c350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
2c360 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ning..*/.int sql
2c370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c380 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 tion(. sqlite3
2c390 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
2c3a0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
2c3b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
2c3c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
2c3d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
2c3e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
2c3f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2c400 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2c410 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
2c420 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
2c430 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
2c440 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
2c450 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
2c460 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
2c470 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
2c480 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
2c490 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
2c4a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
2c4b0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
2c4c0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
2c4d0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
2c4e0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
2c4f0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
2c500 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
2c510 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
2c520 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
2c530 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2c540 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2c550 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
2c560 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
2c570 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c ext*).);.int sql
2c580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c590 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 tion_v2(. sqlit
2c5a0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
2c5b0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e char *zFunctionN
2c5c0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
2c5d0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2c5e0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
2c5f0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
2c600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2c610 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2c620 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
2c630 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
2c640 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2c650 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2c660 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
2c670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c lite3_context*),
2c680 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f . void(*xDestro
2c690 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a y)(void*).);../*
2c6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
2c6b0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a xt Encodings.**.
2c6c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
2c6d0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 t define integer
2c6e0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 codes that repr
2c6f0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 esent the variou
2c700 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 s.** text encodi
2c710 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 ngs supported by
2c720 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 SQLite..*/.#def
2c730 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 ine SQLITE_UTF8
2c740 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
2c750 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
2c760 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 LE 2.#def
2c770 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
2c780 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 BE 3.#def
2c790 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
2c7a0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 4 /
2c7b0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 * Use native byt
2c7c0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 e order */.#defi
2c7d0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 ne SQLITE_ANY
2c7e0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 5 /*
2c7f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2c800 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f function only */
2c810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c820 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
2c830 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
2c840 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
2c850 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
2c860 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
2c870 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ted Functions.**
2c880 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
2c890 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
2c8a0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 s are [deprecate
2c8b0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f d]. In order to
2c8c0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
2c8d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
2c8e0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
2c8f0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 code, these func
2c900 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a tions continue .
2c910 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ** to be support
2c920 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 ed. However, ne
2c930 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
2c940 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
2c950 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
2c960 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 functions. To h
2c970 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 elp encourage pe
2c980 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a ople to avoid.**
2c990 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e using these fun
2c9a0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e ctions, we are n
2c9b0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c ot going to tell
2c9c0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 you what they d
2c9d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
2c9e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
2c9f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 ATED.SQLITE_DEPR
2ca00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2ca10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
2ca20 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
2ca30 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 xt*);.SQLITE_DEP
2ca40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2ca50 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
2ca60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
2ca70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
2ca80 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
2ca90 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
2caa0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
2cab0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
2cac0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2cad0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
2cae0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
2caf0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
2cb00 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 void sqlite3_th
2cb10 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
2cb20 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
2cb30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
2cb40 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
2cb50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
2cb60 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
2cb70 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
2cb80 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a t64);.#endif../*
2cb90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
2cba0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 taining SQL Func
2cbb0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 tion Parameter V
2cbc0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alues.**.** The
2cbd0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 C-language imple
2cbe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c mentation of SQL
2cbf0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
2cc00 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a ggregates uses.*
2cc10 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e * this set of in
2cc20 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 terface routines
2cc30 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 to access the p
2cc40 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 arameter values
2cc50 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 on.** the functi
2cc60 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e on or aggregate.
2cc70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 .**.** The xFunc
2cc80 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e (for scalar fun
2cc90 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 ctions) or xStep
2cca0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 (for aggregates
2ccb0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 ) parameters.**
2ccc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2ccd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
2cce0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
2ccf0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2cd00 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 .** define callb
2cd10 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d acks that implem
2cd20 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
2cd30 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
2cd40 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 ates..** The 3rd
2cd50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2cd60 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 ese callbacks is
2cd70 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
2cd80 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f nters to.** [pro
2cd90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2cda0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
2cdb0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
2cdc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2cdd0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
2cde0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2cdf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
2ce00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
2ce10 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
2ce20 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
2ce30 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
2ce40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
2ce50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
2ce60 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 nes work only wi
2ce70 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 th [protected sq
2ce80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2ce90 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 ects..** Any att
2cea0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 empt to use thes
2ceb0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e e routines on an
2cec0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2ced0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
2cee0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 object results i
2cef0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
2cf00 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 vior..**.** ^The
2cf10 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
2cf20 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
2cf30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
2cf40 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
2cf50 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
2cf60 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
2cf70 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
2cf80 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
2cf90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2cfa0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
2cfb0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
2cfc0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
2cfd0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
2cfe0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
2cff0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
2d000 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2d010 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 16() interface e
2d020 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 xtracts a UTF-16
2d030 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 string.** in th
2d040 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 e native byte-or
2d050 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
2d060 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a machine. ^The.*
2d070 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f * sqlite3_value_
2d080 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 text16be() and s
2d090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d0a0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 t16le() interfac
2d0b0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 es.** extract UT
2d0c0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 F-16 strings as
2d0d0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c big-endian and l
2d0e0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 ittle-endian res
2d0f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a pectively..**.**
2d100 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ^(The sqlite3_v
2d110 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
2d120 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 e() interface at
2d130 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a tempts to apply.
2d140 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e ** numeric affin
2d150 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ity to the value
2d160 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 . This means th
2d170 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 at an attempt is
2d180 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 .** made to conv
2d190 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f ert the value to
2d1a0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 an integer or f
2d1b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 loating point.
2d1c0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e If.** such a con
2d1d0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 version is possi
2d1e0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 ble without loss
2d1f0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 of information
2d200 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 (in other.** wor
2d210 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 ds, if the value
2d220 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 is a string tha
2d230 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
2d240 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 umber).** then t
2d250 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 he conversion is
2d260 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 performed. Oth
2d270 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 erwise no conver
2d280 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 sion occurs..**
2d290 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 The [SQLITE_INTE
2d2a0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 GER | datatype]
2d2b0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e after conversion
2d2c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a is returned.)^.
2d2d0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 **.** Please pay
2d2e0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 particular atte
2d2f0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 ntion to the fac
2d300 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 t that the point
2d310 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 er returned.** f
2d320 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c rom [sqlite3_val
2d330 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c ue_blob()], [sql
2d340 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
2d350 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
2d360 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
2d370 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 )] can be invali
2d380 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 dated by a subse
2d390 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a quent call to.**
2d3a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2d3b0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 bytes()], [sqlit
2d3c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
2d3d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
2d3e0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
2d3f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
2d400 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a e_text16()]..**.
2d410 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2d420 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
2d430 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
2d440 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 hread as.** the
2d450 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 SQL function tha
2d460 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b t supplied the [
2d470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 sqlite3_value*]
2d480 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 parameters..*/.c
2d490 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2d4a0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
2d4b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2d4c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
2d4d0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
2d4e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
2d4f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
2d500 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
2d510 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
2d520 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
2d530 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2d540 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2d550 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
2d560 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
2d570 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
2d580 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
2d590 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
2d5a0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
2d5b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d5c0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
2d5d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2d5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d5f0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
2d600 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
2d610 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
2d620 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
2d630 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
2d640 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
2d650 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
2d660 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
2d670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2d680 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2d690 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
2d6a0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
2d6b0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2d6c0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
2d6d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
2d6e0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
2d6f0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d Context.**.** Im
2d700 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2d710 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
2d720 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 unctions use thi
2d730 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 s.** routine to
2d740 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
2d750 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 for storing thei
2d760 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e r state..**.** ^
2d770 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
2d780 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 he sqlite3_aggre
2d790 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
2d7a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
2d7b0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 led .** for a pa
2d7c0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 rticular aggrega
2d7d0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c te function, SQL
2d7e0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 ite.** allocates
2d7f0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 N of memory, ze
2d800 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 roes out that me
2d810 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e mory, and return
2d820 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
2d830 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 o the new memory
2d840 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 . ^On second and
2d850 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
2d860 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
2d870 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
2d880 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 t() for the same
2d890 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
2d8a0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a ion instance,.**
2d8b0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
2d8c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 is returned. S
2d8d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2d8e0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f _context() is no
2d8f0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 rmally.** called
2d900 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 once for each i
2d910 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 nvocation of the
2d920 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 xStep callback
2d930 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 and then one.**
2d940 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 last time when t
2d950 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 he xFinal callba
2d960 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 ck is invoked.
2d970 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d ^(When no rows m
2d980 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 atch.** an aggre
2d990 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 gate query, the
2d9a0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b xStep() callback
2d9b0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
2d9c0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d e function.** im
2d9d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
2d9e0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 never called and
2d9f0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c xFinal() is cal
2da00 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 led exactly once
2da10 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 ..** In those ca
2da20 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 ses, sqlite3_agg
2da30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
2da40 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 might be called
2da50 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 for the.** firs
2da60 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 t time from with
2da70 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a in xFinal().)^.*
2da80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2da90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
2daa0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 ext(C,N) routine
2dab0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
2dac0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a pointer if N is.
2dad0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 ** less than or
2dae0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 equal to zero or
2daf0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2db00 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 ocate error occu
2db10 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 rs..**.** ^(The
2db20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 amount of space
2db30 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
2db40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2db50 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a ontext(C,N) is.*
2db60 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 * determined by
2db70 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
2db80 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 on first success
2db90 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 ful call. Chang
2dba0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 ing the.** value
2dbb0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 of N in subsequ
2dbc0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
2dbd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2dbe0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a ntext() within.*
2dbf0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 * the same aggre
2dc00 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
2dc10 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 stance will not
2dc20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 resize the memor
2dc30 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e y.** allocation.
2dc40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
2dc50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
2dc60 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 rees the memory
2dc70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a allocated by .**
2dc80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
2dc90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 te_context() whe
2dca0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 n the aggregate
2dcb0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e query concludes.
2dcc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
2dcd0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
2dce0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 be a copy of the
2dcf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
2dd00 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 text | SQL funct
2dd10 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 ion context] tha
2dd20 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 t is the first p
2dd30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
2dd40 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e he xStep or xFin
2dd50 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 al callback rout
2dd60 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ine that impleme
2dd70 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 nts the aggregat
2dd80 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a e.** function..*
2dd90 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2dda0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
2ddb0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
2ddc0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
2ddd0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
2dde0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
2ddf0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 running..*/.void
2de00 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 *sqlite3_aggreg
2de10 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 ate_context(sqli
2de20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2de30 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a t nBytes);../*.*
2de40 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 * CAPI3REF: User
2de50 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 Data For Functi
2de60 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ons.**.** ^The s
2de70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
2de80 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
2de90 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
2dea0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 * the pointer th
2deb0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 at was the pUser
2dec0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 Data parameter (
2ded0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
2dee0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
2def0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2df00 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
2df10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2df20 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
2df30 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
2df40 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
2df50 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
2df60 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
2df70 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
2df80 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
2df90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
2dfa0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
2dfb0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
2dfc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2dfd0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
2dfe0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
2dff0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
2e000 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
2e010 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2e020 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
2e030 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
2e040 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 nctions.**.** ^T
2e050 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 he sqlite3_conte
2e060 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 xt_db_handle() i
2e070 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2e080 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
2e090 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
2e0a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2e0b0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 ction] (the 1st
2e0c0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
2e0d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2e0e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
2e0f0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2e100 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2e110 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
2e120 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
2e130 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
2e140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
2e150 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
2e160 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
2e170 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
2e180 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e ndle(sqlite3_con
2e190 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
2e1a0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
2e1b0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 n Auxiliary Data
2e1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f .**.** The follo
2e1d0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f wing two functio
2e1e0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 ns may be used b
2e1f0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e y scalar SQL fun
2e200 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 ctions to.** ass
2e210 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 ociate metadata
2e220 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 with argument va
2e230 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d lues. If the sam
2e240 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 e value is passe
2e250 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 d to.** multiple
2e260 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
2e270 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e the same SQL fun
2e280 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 ction during que
2e290 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e ry execution, un
2e2a0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 der.** some circ
2e2b0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 umstances the as
2e2c0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 sociated metadat
2e2d0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 a may be preserv
2e2e0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 ed. This may.**
2e2f0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 be used, for exa
2e300 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 mple, to add a r
2e310 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f egular-expressio
2e320 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 n matching scala
2e330 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 r.** function. T
2e340 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 he compiled vers
2e350 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c ion of the regul
2e360 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 ar expression is
2e370 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 stored as.** me
2e380 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 tadata associate
2e390 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 d with the SQL v
2e3a0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
2e3b0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
2e3c0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e ssion.** pattern
2e3d0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 . The compiled
2e3e0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
2e3f0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
2e400 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
2e410 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
2e420 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2e430 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 so that the ori
2e440 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 ginal pattern st
2e450 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ring.** does not
2e460 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f need to be reco
2e470 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 mpiled on each i
2e480 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a nvocation..**.**
2e490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
2e4a0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
2e4b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2e4c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
2e4d0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 etadata.** assoc
2e4e0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c iated by the sql
2e4f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
2e500 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 () function with
2e510 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
2e520 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 t.** value to th
2e530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2e540 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
2e550 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 ^If no metadata
2e560 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a has been ever.**
2e570 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 been set for th
2e580 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f e Nth argument o
2e590 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 f the function,
2e5a0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 or if the corres
2e5b0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 ponding.** funct
2e5c0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 ion parameter ha
2e5d0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 s changed since
2e5e0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 the meta-data wa
2e5f0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 s set,.** then s
2e600 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2e610 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e ta() returns a N
2e620 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
2e630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2e640 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e set_auxdata() in
2e650 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 terface saves th
2e660 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f e metadata.** po
2e670 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 inted to by its
2e680 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 3rd parameter as
2e690 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f the metadata fo
2e6a0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 r the N-th.** ar
2e6b0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 gument of the ap
2e6c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2e6d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 d function. Sub
2e6e0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
2e6f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f to sqlite3_get_
2e700 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 auxdata() might
2e710 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 return this data
2e720 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e , if it has.** n
2e730 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 ot been destroye
2e740 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 d..** ^If it is
2e750 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 not NULL, SQLite
2e760 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 will invoke the
2e770 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 destructor.** f
2e780 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 unction given by
2e790 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
2e7a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 er to sqlite3_se
2e7b0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a t_auxdata() on.*
2e7c0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 * the metadata w
2e7d0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
2e7e0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 nding function p
2e7f0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 arameter changes
2e800 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 .** or when the
2e810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
2e820 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 mpletes, whichev
2e830 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a er comes first..
2e840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 **.** SQLite is
2e850 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 free to call the
2e860 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 destructor and
2e870 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e drop metadata on
2e880 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 any.** paramete
2e890 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f r of any functio
2e8a0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 n at any time.
2e8b0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e ^The only guaran
2e8c0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 tee is that.** t
2e8d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 he destructor wi
2e8e0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 ll be called bef
2e8f0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 ore the metadata
2e900 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a is dropped..**.
2e910 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 ** ^(In practice
2e920 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 , metadata is pr
2e930 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 eserved between
2e940 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 function calls f
2e950 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e or.** expression
2e960 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 s that are const
2e970 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 ant at compile t
2e980 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 ime. This includ
2e990 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 es literal.** va
2e9a0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 lues and [parame
2e9b0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 ters].)^.**.** T
2e9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
2e9d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
2e9e0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
2e9f0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
2ea00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
2ea10 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f s running..*/.vo
2ea20 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
2ea30 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
2ea40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 context*, int N)
2ea50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 ;.void sqlite3_s
2ea60 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
2ea70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
2ea80 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
2ea90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
2eaa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
2eab0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
2eac0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
2ead0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a ctor Behavior.**
2eae0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 .** These are sp
2eaf0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 ecial values for
2eb00 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
2eb10 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 that is passed i
2eb20 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 n as the.** fina
2eb30 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f l argument to ro
2eb40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
2eb50 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
2eb60 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 ()]. ^If the de
2eb70 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 structor.** argu
2eb80 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 ment is SQLITE_S
2eb90 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 TATIC, it means
2eba0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
2ebb0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 pointer is cons
2ebc0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c tant.** and will
2ebd0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 never change.
2ebe0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 It does not need
2ebf0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 to be destroyed
2ec00 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 . ^The.** SQLIT
2ec10 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
2ec20 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
2ec30 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
2ec40 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
2ec50 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
2ec60 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
2ec70 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
2ec80 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
2ec90 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
2eca0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
2ecb0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
2ecc0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
2ecd0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
2ece0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
2ecf0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
2ed00 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 compilers. See
2ed10 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f ticket #2191..*/
2ed20 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
2ed30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
2ed40 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
2ed50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2ed60 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
2ed70 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
2ed80 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
2ed90 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
2eda0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
2edb0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
2edc0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
2edd0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
2ede0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
2edf0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 Function.**.** T
2ee00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
2ee10 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
2ee20 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
2ee30 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
2ee40 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
2ee50 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
2ee60 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
2ee70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2ee80 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
2ee90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2eea0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
2eeb0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
2eec0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
2eed0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
2eee0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
2eef0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
2ef00 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
2ef10 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
2ef20 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
2ef30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
2ef40 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
2ef50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ef60 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
2ef70 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
2ef80 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
2ef90 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
2efa0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
2efb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2efc0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
2efd0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
2efe0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
2eff0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
2f000 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
2f010 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
2f020 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
2f030 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
2f040 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
2f050 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
2f060 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
2f070 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
2f080 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
2f090 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
2f0a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
2f0b0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
2f0c0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
2f0d0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
2f0e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2f0f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
2f100 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
2f110 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
2f120 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
2f130 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
2f140 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
2f150 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
2f160 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
2f170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
2f180 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
2f190 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
2f1a0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
2f1b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2f1c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2f1d0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
2f1e0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
2f1f0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
2f200 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
2f210 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2f220 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
2f230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2f240 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
2f250 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
2f260 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
2f270 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
2f280 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
2f290 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
2f2a0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 he string pointe
2f2b0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 d to by the.** 2
2f2c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
2f2d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2f2e0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 rror() or sqlite
2f2f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
2f300 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 ().** as the tex
2f310 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 t of an error me
2f320 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 ssage. ^SQLite
2f330 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
2f340 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
2f350 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
2f360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2f370 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 () as UTF-8. ^SQ
2f380 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
2f390 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
2f3a0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
2f3b0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
2f3c0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
2f3d0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
2f3e0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
2f3f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2f400 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
2f410 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2f420 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
2f430 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
2f440 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
2f450 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
2f460 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
2f470 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
2f480 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
2f490 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
2f4a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
2f4b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
2f4c0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
2f4d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2f4e0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
2f4f0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
2f500 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
2f510 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
2f520 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
2f530 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
2f540 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
2f550 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e or message..** ^
2f560 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2f570 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
2f580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2f590 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 ror16().** routi
2f5a0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 nes make a priva
2f5b0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 te copy of the e
2f5c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
2f5d0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 t before.** they
2f5e0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c return. Hence,
2f5f0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
2f600 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f ction can deallo
2f610 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 cate or.** modif
2f620 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 y the text after
2f630 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 they return wit
2f640 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 hout harm..** ^T
2f650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2f660 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 t_error_code() f
2f670 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 unction changes
2f680 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a the error code.*
2f690 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 * returned by SQ
2f6a0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 Lite as a result
2f6b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 of an error in
2f6c0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 a function. ^By
2f6d0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
2f6e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
2f6f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 QLITE_ERROR. ^A
2f700 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
2f710 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
2f720 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
2f730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2f740 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
2f750 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
2f760 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
2f770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f780 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 te3_result_toobi
2f790 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
2f7a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
2f7b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
2f7c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
2f7d0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f a string or BLO
2f7e0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f B is too long to
2f7f0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a represent..**.*
2f800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
2f810 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e esult_nomem() in
2f820 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
2f830 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
2f840 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 n error.** indic
2f850 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d ating that a mem
2f860 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
2f870 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ailed..**.** ^Th
2f880 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2f890 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 _int() interface
2f8a0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
2f8b0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
2f8c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2f8d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
2f8e0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 be the 32-bit s
2f8f0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
2f900 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
2f910 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
2f920 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2f930 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
2f940 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
2f950 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
2f960 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
2f970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2f980 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
2f990 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
2f9a0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
2f9b0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
2f9c0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
2f9d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
2f9e0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 esult_null() int
2f9f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
2fa00 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
2fa10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
2fa20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2fa30 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a ion to be NULL..
2fa40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2fa50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 e3_result_text()
2fa60 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 , sqlite3_result
2fa70 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 _text16(),.** sq
2fa80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2fa90 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c t16le(), and sql
2faa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2fab0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 16be() interface
2fac0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 s.** set the ret
2fad0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
2fae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2faf0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
2fb00 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 be.** a text st
2fb10 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 ring which is re
2fb20 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 presented as UTF
2fb30 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 -8, UTF-16 nativ
2fb40 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a e byte order,.**
2fb50 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 UTF-16 little e
2fb60 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
2fb70 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 big endian, res
2fb80 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 pectively..** ^S
2fb90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 QLite takes the
2fba0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d text result from
2fbb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2fbc0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 from.** the 2nd
2fbd0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 parameter of th
2fbe0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2fbf0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
2fc00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 s..** ^If the 3r
2fc10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
2fc20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2fc30 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
2fc40 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 es.** is negativ
2fc50 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 e, then SQLite t
2fc60 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 akes result text
2fc70 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
2fc80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 rameter.** throu
2fc90 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
2fca0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
2fcb0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
2fcc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
2fcd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2fce0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
2fcf0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
2fd00 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 then as many by
2fd10 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
2fd20 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 ers) of the text
2fd30 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
2fd40 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
2fd50 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 ter are taken as
2fd60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2fd70 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 -defined.** func
2fd80 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 tion result..**
2fd90 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
2fda0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
2fdb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2fdc0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
2fdd0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
2fde0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d t_blob is a non-
2fdf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
2fe00 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 en SQLite calls
2fe10 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e that.** function
2fe20 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 as the destruct
2fe30 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f or on the text o
2fe40 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 r BLOB result wh
2fe50 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e en it has.** fin
2fe60 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
2fe70 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
2fe80 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
2fe90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
2fea0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
2feb0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a terfaces or to.*
2fec0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
2fed0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
2fee0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
2fef0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 LITE_STATIC, the
2ff00 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 n SQLite.** assu
2ff10 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 mes that the tex
2ff20 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 t or BLOB result
2ff30 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 is in constant
2ff40 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
2ff50 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 ot.** copy the c
2ff60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 ontent of the pa
2ff70 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c rameter nor call
2ff80 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e a destructor on
2ff90 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 the content.**
2ffa0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 when it has fini
2ffb0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 shed using that
2ffc0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 result..** ^If t
2ffd0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
2ffe0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
2fff0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
30000 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
30010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
30020 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c b is the special
30030 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 constant SQLITE
30040 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 _TRANSIENT.** th
30050 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 en SQLite makes
30060 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 a copy of the re
30070 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 sult into space
30080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a obtained from.**
30090 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
300a0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 alloc()] before
300b0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
300c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
300d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
300e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
300f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
30100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
30110 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
30120 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a o be a copy the.
30130 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
30140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30150 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 bject specified
30160 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
30170 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 eter. ^The.** s
30180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
30190 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 lue() interface
301a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
301b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
301c0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 ue].** so that t
301d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
301e0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 e] specified in
301f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 the parameter ma
30200 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 y change or.** b
30210 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 e deallocated af
30220 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 ter sqlite3_resu
30230 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 lt_value() retur
30240 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e ns without harm.
30250 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 .** ^A [protecte
30260 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
30270 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 object may alwa
30280 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 ys be used where
30290 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
302a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
302b0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 e] object is req
302c0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 uired, so either
302d0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c .** kind of [sql
302e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
302f0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 ct can be used w
30300 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 ith this interfa
30310 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ce..**.** If the
30320 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
30330 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
30340 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 in the different
30350 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 thread.** than
30360 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 the one containi
30370 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ng the applicati
30380 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
30390 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 ion that receive
303a0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 d.** the [sqlite
303b0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 3_context] point
303c0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 er, the results
303d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
303e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
303f0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
30400 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
30410 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
30420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
30430 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
30440 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
30450 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
30460 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
30470 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
30480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
30490 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
304a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
304b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
304c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
304d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
304e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
304f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
30500 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 toobig(sqlite3_c
30510 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
30520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
30530 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 ror_nomem(sqlite
30540 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
30550 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
30560 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 _error_code(sqli
30570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
30580 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
30590 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
305a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
305b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
305c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
305d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
305e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
305f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
30600 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
30610 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
30620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30630 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
30640 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
30650 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
30660 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
30670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
30680 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
30690 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
306a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
306b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
306c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
306d0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
306e0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
306f0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
30700 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
30710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
30720 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
30730 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
30740 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
30750 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
30760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30770 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
30780 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
30790 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
307a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
307b0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
307c0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
307d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
307e0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
307f0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a ating Sequences.
30800 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
30810 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f ctions add, remo
30820 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 ve, or modify a
30830 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f [collation] asso
30840 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 ciated.** with t
30850 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
30860 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
30870 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
30880 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
30890 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
308a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 collation is a
308b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
308c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
308d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 te_collation() a
308e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nd sqlite3_creat
308f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
30900 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 .** and a UTF-16
30910 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 string in nativ
30920 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 e byte order for
30930 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
30940 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a collation16()..*
30950 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d * ^Collation nam
30960 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 es that compare
30970 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 equal according
30980 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e to [sqlite3_strn
30990 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 icmp()] are.** c
309a0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 onsidered to be
309b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a the same name..*
309c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 *.** ^(The third
309d0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 argument (eText
309e0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 Rep) must be one
309f0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 of the constant
30a00 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c s:.** <ul>.** <l
30a10 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d i> [SQLITE_UTF8]
30a20 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
30a30 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c E_UTF16LE],.** <
30a40 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
30a50 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 6BE],.** <li> [S
30a60 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 QLITE_UTF16], or
30a70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
30a80 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e _UTF16_ALIGNED].
30a90 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e .** </ul>)^.** ^
30aa0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 The eTextRep arg
30ab0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 ument determines
30ac0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 the encoding of
30ad0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a strings passed.
30ae0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 ** to the collat
30af0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c ing function cal
30b00 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b lback, xCallback
30b10 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
30b20 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 E_UTF16] and [SQ
30b30 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
30b40 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 ED] values for e
30b50 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 TextRep.** force
30b60 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 strings to be U
30b70 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 TF16 with native
30b80 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
30b90 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 ^The [SQLITE_UTF
30ba0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 16_ALIGNED] valu
30bb0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 e for eTextRep f
30bc0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f orces strings to
30bd0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 begin.** on an
30be0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 even byte addres
30bf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f s..**.** ^The fo
30c00 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 urth argument, p
30c10 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 Arg, is an appli
30c20 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
30c30 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 ter that is pass
30c40 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 ed.** through as
30c50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
30c60 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 ent to the colla
30c70 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
30c80 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 llback..**.** ^T
30c90 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
30ca0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 t, xCallback, is
30cb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
30cc0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
30cd0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 tion..** ^Multip
30ce0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e le collating fun
30cf0 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 ctions can be re
30d00 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 gistered using t
30d10 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
30d20 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 .** with differe
30d30 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 nt eTextRep para
30d40 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 meters and SQLit
30d50 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 e will use which
30d60 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ever.** function
30d70 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 requires the le
30d80 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 ast amount of da
30d90 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f ta transformatio
30da0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 n..** ^If the xC
30db0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
30dc0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 is NULL then th
30dd0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
30de0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 tion is.** delet
30df0 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 ed. ^When all c
30e00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
30e10 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 ns having the sa
30e20 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 me name are dele
30e30 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c ted,.** that col
30e40 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e lation is no lon
30e50 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a ger usable..**.*
30e60 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 * ^The collating
30e70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
30e80 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
30e90 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 th a copy of the
30ea0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 pArg .** applic
30eb0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
30ec0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 er and with two
30ed0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 strings in the e
30ee0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 ncoding specifie
30ef0 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 d.** by the eTex
30f00 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 tRep argument.
30f10 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 The collating fu
30f20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 nction must retu
30f30 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 rn an.** integer
30f40 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 that is negativ
30f50 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 e, zero, or posi
30f60 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 tive.** if the f
30f70 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c irst string is l
30f80 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 ess than, equal
30f90 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 to, or greater t
30fa0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a han the second,.
30fb0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
30fc0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 A collating fu
30fd0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 nction must alwa
30fe0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ys return the sa
30ff0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 me answer.** giv
31000 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 en the same inpu
31010 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d ts. If two or m
31020 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ore collating fu
31030 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 nctions are regi
31040 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 stered.** to the
31050 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 same collation
31060 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 name (using diff
31070 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 erent eTextRep v
31080 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a alues) then all.
31090 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 ** must give an
310a0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 equivalent answe
310b0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 r when invoked w
310c0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 ith equivalent s
310d0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 trings..** The c
310e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
310f0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 n must obey the
31100 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 following proper
31110 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 ties for all.**
31120 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e strings A, B, an
31130 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a d C:.**.** <ol>.
31140 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 ** <li> If A==B
31150 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c then B==A..** <l
31160 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 i> If A==B and B
31170 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a ==C then A==C..*
31180 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
31190 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a THEN B>A..**
311a0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 <li> If A<B
311b0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 and B<C then
311c0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e A<C..** </ol>
311d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c .**.** If a coll
311e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 ating function f
311f0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 ails any of the
31200 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 above constraint
31210 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f s and that.** co
31220 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
31230 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 is registered
31240 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 and used, then t
31250 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 he behavior of S
31260 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 QLite.** is unde
31270 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
31280 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
31290 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
312a0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
312b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
312c0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 ion().** with th
312d0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 e addition that
312e0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c the xDestroy cal
312f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
31300 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a on pArg when.**
31310 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
31320 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
31330 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e ed..** ^Collatin
31340 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 g functions are
31350 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 deleted when the
31360 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
31370 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c by later.** cal
31380 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 ls to the collat
31390 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e ion creation fun
313a0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 ctions or when t
313b0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
313c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 connection] is c
313d0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c losed using [sql
313e0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
313f0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 *.** ^The xDestr
31400 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c oy callback is <
31410 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 u>not</u> called
31420 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 if the .** sqli
31430 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
31440 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 tion_v2() functi
31450 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 on fails. Appli
31460 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 cations that inv
31470 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 oke.** sqlite3_c
31480 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
31490 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d v2() with a non-
314a0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 NULL xDestroy ar
314b0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a gument should .*
314c0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 * check the retu
314d0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 rn code and disp
314e0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ose of the appli
314f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
31500 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 ter.** themselve
31510 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 s rather than ex
31520 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 pecting SQLite t
31530 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 o deal with it f
31540 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 or them..** This
31550 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 is different fr
31560 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 om every other S
31570 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
31580 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 The inconsiste
31590 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 ncy .** is unfor
315a0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f tunate but canno
315b0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 t be changed wit
315c0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 hout breaking ba
315d0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 ckwards .** comp
315e0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
315f0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c See also: [sql
31600 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
31610 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 eeded()] and [sq
31620 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
31630 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a needed16()]..*/.
31640 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
31650 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 te_collation(.
31660 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
31670 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
31680 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
31690 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a . void *pArg,.
316a0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
316b0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
316c0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
316d0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 void*).);.int s
316e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
316f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
31700 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
31710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
31720 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
31730 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 void *pArg,.
31740 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
31750 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
31760 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
31770 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 oid*),. void(*x
31780 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
31790 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
317a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
317b0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
317c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e const void *zN
317d0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 ame,. int eText
317e0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 Rep, . void *pA
317f0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 rg,. int(*xComp
31800 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
31810 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
31820 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
31830 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31840 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 Collation Needed
31850 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
31860 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e ^To avoid havin
31870 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
31880 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
31890 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
318a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
318b0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
318c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
318d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
318e0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
318f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
31900 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 ction] to be inv
31910 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
31920 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
31930 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
31940 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
31950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 .** ^If the func
31960 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 tion is register
31970 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c ed using the sql
31980 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
31990 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 eeded() API,.**
319a0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 then it is passe
319b0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 d the names of u
319c0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
319d0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 on sequences as
319e0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 strings.** encod
319f0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 ed in UTF-8. ^If
31a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
31a10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 on_needed16() is
31a20 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 used,.** the na
31a30 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 mes are passed a
31a40 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 s UTF-16 in mach
31a50 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 ine native byte
31a60 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c order..** ^A cal
31a70 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 l to either func
31a80 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 tion replaces th
31a90 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 e existing colla
31aa0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c tion-needed call
31ab0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 back..**.** ^(Wh
31ac0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
31ad0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 is invoked, the
31ae0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 first argument p
31af0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a assed is a copy.
31b00 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ** of the second
31b10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
31b20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
31b30 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 eeded() or.** sq
31b40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
31b50 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 needed16(). The
31b60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
31b70 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
31b80 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
31b90 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
31ba0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 ent is one of [S
31bb0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 QLITE_UTF8], [SQ
31bc0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a LITE_UTF16BE],.*
31bd0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 * or [SQLITE_UTF
31be0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 16LE], indicatin
31bf0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 g the most desir
31c00 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 able form of the
31c10 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
31c20 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 quence function
31c30 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 required. The f
31c40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
31c50 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
31c60 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 he.** required c
31c70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
31c80 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 e.)^.**.** The c
31c90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
31ca0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 should register
31cb0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
31cc0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 lation using.**
31cd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
31ce0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 collation()], [s
31cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
31d00 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 llation16()], or
31d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
31d20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
31d30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
31d40 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
31d50 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a eded(. sqlite3*
31d60 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 , . void*, . v
31d70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
31d80 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
31d90 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a ep,const char*).
31da0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
31db0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
31dc0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
31dd0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 void*,. void(
31de0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
31df0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
31e00 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
31e10 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 #ifdef SQLITE_HA
31e20 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 S_CODEC./*.** Sp
31e30 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f ecify the key fo
31e40 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 r an encrypted d
31e50 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 atabase. This r
31e60 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 outine should be
31e70 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 .** called right
31e80 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f after sqlite3_o
31e90 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 pen()..**.** The
31ea0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 code to impleme
31eb0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e nt this API is n
31ec0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ot available in
31ed0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 the public relea
31ee0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e se.** of SQLite.
31ef0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
31f00 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
31f10 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
31f20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
31f30 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
31f40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
31f50 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
31f60 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a /* The key *
31f70 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e /.);../*.** Chan
31f80 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e ge the key on an
31f90 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 open database.
31fa0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 If the current
31fb0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a database is not.
31fc0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 ** encrypted, th
31fd0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
31fe0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 encrypt it. If
31ff0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d pNew==0 or nNew=
32000 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 =0, the.** datab
32010 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 ase is decrypted
32020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
32030 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
32040 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
32050 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
32060 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
32070 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
32080 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 nt sqlite3_rekey
32090 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
320a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
320b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 /* Database t
320c0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a o be rekeyed */.
320d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b const void *pK
320e0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 ey, int nKey
320f0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 /* The new key
32100 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 */.);../*.** Spe
32110 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 cify the activat
32120 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 ion key for a SE
32130 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c E database. Unl
32140 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
32150 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 d, none of the S
32160 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c EE routines will
32170 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 work..*/.void s
32180 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f qlite3_activate_
32190 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 see(. const cha
321a0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
321b0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
321c0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
321d0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
321e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 SQLITE_ENABLE_CE
321f0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 ROD./*.** Specif
32200 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e y the activation
32210 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 key for a CEROD
32220 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
32230 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
32240 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 , none of the CE
32250 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c ROD routines wil
32260 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
32270 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
32280 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
32290 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
322a0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
322b0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
322c0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
322d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
322e0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
322f0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
32300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
32310 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
32320 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
32330 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
32340 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
32350 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
32360 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
32370 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
32380 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
32390 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
323a0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
323b0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
323c0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
323d0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
323e0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
323f0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
32400 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
32410 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
32420 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
32430 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
32440 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
32450 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
32460 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
32470 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
32480 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
32490 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
324a0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
324b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
324c0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
324d0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
324e0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
324f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
32500 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
32510 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
32520 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
32530 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
32540 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
32550 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
32560 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
32570 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
32580 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
32590 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
325a0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
325b0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
325c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
325d0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
325e0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 3_sleep(int);../
325f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
32600 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 ame Of The Folde
32610 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 r Holding Tempor
32620 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 ary Files.**.**
32630 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c ^(If this global
32640 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 variable is mad
32650 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 e to point to a
32660 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a string which is.
32670 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
32680 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 folder (a.k.a.
32690 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
326a0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
326b0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
326c0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 by SQLite when u
326d0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
326e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
326f0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 FS].** will be p
32700 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
32710 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 rectory.)^ ^If
32720 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
32730 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
32740 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
32750 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
32760 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
32770 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
32780 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
32790 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
327a0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
327b0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
327c0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
327d0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
327e0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
327f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
32800 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
32810 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
32820 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
32830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
32840 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
32850 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
32860 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
32870 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
32880 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
32890 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
328a0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
328b0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
328c0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
328d0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
328e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
328f0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
32900 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
32910 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
32920 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
32930 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
32940 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 ** ^The [temp_st
32950 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
32960 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
32970 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
32980 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
32990 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
329a0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
329b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
329c0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
329d0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 .** the [temp_st
329e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
329f0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
32a00 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
32a10 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
32a20 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
32a30 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
32a40 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
32a50 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
32a60 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
32a70 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
32a80 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
32a90 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
32aa0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
32ab0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
32ac0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
32ad0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
32ae0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
32af0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
32b00 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
32b10 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
32b20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
32b30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
32b40 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
32b50 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 of the [temp_st
32b60 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
32b70 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
32b80 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
32b90 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
32ba0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
32bb0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
32bc0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
32bd0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
32be0 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 de.** KEYWORDS:
32bf0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 {autocommit mode
32c00 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c }.**.** ^The sql
32c10 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
32c20 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 mit() interface
32c30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
32c40 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 or.** zero if t
32c50 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 he given databas
32c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
32c70 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
32c80 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a ocommit mode,.**
32c90 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 respectively.
32ca0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 ^Autocommit mode
32cb0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
32cc0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
32cd0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c t mode is disabl
32ce0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 ed by a [BEGIN]
32cf0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 statement..** ^A
32d00 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
32d10 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 s re-enabled by
32d20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 a [COMMIT] or [R
32d30 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 OLLBACK]..**.**
32d40 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 If certain kinds
32d50 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 of errors occur
32d60 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 on a statement
32d70 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 within a multi-s
32d80 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e tatement.** tran
32d90 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 saction (errors
32da0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 including [SQLIT
32db0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_FULL], [SQLITE
32dc0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c _IOERR],.** [SQL
32dd0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
32de0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b ITE_BUSY], and [
32df0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
32e00 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 ]) then the.** t
32e10 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 ransaction might
32e20 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
32e30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
32e40 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a The only way to.
32e50 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 ** find out whet
32e60 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d her SQLite autom
32e70 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
32e80 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
32e90 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e tion after.** an
32ea0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 error is to use
32eb0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a this function..
32ec0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
32ed0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
32ee0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
32ef0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
32f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
32f10 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
32f20 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
32f30 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
32f40 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
32f50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
32f60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
32f70 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
32f80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
32f90 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
32fa0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
32fb0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
32fc0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ment.**.** ^The
32fd0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
32fe0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 e interface retu
32ff0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 rns the [databas
33000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
33010 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 ndle.** to which
33020 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
33030 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
33040 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 ^The [database
33050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
33060 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
33070 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
33080 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
33090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
330a0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 ** that was the
330b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
330c0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
330d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
330e0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 call (or its var
330f0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 iants) that was
33100 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 used to.** creat
33110 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
33120 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
33130 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a ce..*/.sqlite3 *
33140 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
33150 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 e(sqlite3_stmt*)
33160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33170 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 F: Find the next
33180 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
33190 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ent.**.** ^This
331a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
331b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
331c0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
331d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
331e0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
331f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
33200 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
33210 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 tion] pDb. ^If
33220 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a pStmt is NULL.**
33230 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 then this inter
33240 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
33250 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 ointer to the fi
33260 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 rst prepared sta
33270 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 tement.** associ
33280 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 ated with the da
33290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
332a0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 n pDb. ^If no p
332b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
332c0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 t.** satisfies t
332d0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 he conditions of
332e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 this routine, i
332f0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a t returns NULL..
33300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 **.** The [datab
33310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
33320 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 pointer D in a c
33330 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
33340 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
33350 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
33360 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
33370 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
33380 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 and in particula
33390 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 r must not be a
333a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
333b0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 .sqlite3_stmt *s
333c0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
333d0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 (sqlite3 *pDb, s
333e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
333f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
33400 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 3REF: Commit And
33410 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 Rollback Notifi
33420 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
33430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33440 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
33450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
33460 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
33470 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
33480 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
33490 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
334a0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 n is [COMMIT | c
334b0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 ommitted]..** ^A
334c0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
334d0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
334e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
334f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
33500 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
33510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
33520 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
33530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
33540 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 ollback_hook() i
33550 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
33560 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
33570 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33580 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
33590 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
335a0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f s [ROLLBACK | ro
335b0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e lled back]..** ^
335c0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
335d0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
335e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
335f0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a ollback_hook().*
33600 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
33610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
33620 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
33630 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 ..** ^The pArg a
33640 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
33650 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
33660 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 callback..** ^I
33670 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f f the callback o
33680 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 n a commit hook
33690 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
336a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 non-zero,.** th
336b0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 en the commit is
336c0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 converted into
336d0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a a rollback..**.*
336e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
336f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 ommit_hook(D,C,P
33700 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f ) and sqlite3_ro
33710 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c llback_hook(D,C,
33720 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 P) functions.**
33730 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 return the P arg
33740 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 ument from the p
33750 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 revious call of
33760 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
33770 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 n.** on the same
33780 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
33790 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c ction] D, or NUL
337a0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 L for.** the fir
337b0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 st call for each
337c0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a function on D..
337d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
337e0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ck implementatio
337f0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
33800 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
33810 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
33820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
33830 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
33840 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 the callback. A
33850 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
33860 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
33870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
33880 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
33890 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
338a0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
338b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
338c0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
338d0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 triggered the c
338e0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c ommit.** or roll
338f0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 back hook in the
33900 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
33910 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
33920 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
33930 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
33940 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
33950 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
33960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
33970 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
33980 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
33990 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
339a0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 **.** ^Registeri
339b0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 ng a NULL functi
339c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 on disables the
339d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
339e0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 ^When the commit
339f0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 hook callback r
33a00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
33a10 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 ero, the [COMMIT
33a20 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 ].** operation i
33a30 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e s allowed to con
33a40 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 tinue normally.
33a50 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 ^If the commit
33a60 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 hook.** returns
33a70 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
33a80 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 he [COMMIT] is c
33a90 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
33aa0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e [ROLLBACK]..** ^
33ab0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f The rollback hoo
33ac0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 k is invoked on
33ad0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 a rollback that
33ae0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 results from a c
33af0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 ommit.** hook re
33b00 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f turning non-zero
33b10 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 , just as it wou
33b20 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f ld be with any o
33b30 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ther rollback..*
33b40 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
33b50 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 rposes of this A
33b60 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f PI, a transactio
33b70 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 n is said to hav
33b80 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 e been.** rolled
33b90 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c back if an expl
33ba0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 icit "ROLLBACK"
33bb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 statement is exe
33bc0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 cuted, or.** an
33bd0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 error or constra
33be0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d int causes an im
33bf0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 plicit rollback
33c00 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 to occur..** ^Th
33c10 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
33c20 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
33c30 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
33c40 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
33c50 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
33c60 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
33c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33c80 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
33c90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
33ca0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 e [sqlite3_updat
33cb0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 e_hook()] interf
33cc0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ace..*/.void *sq
33cd0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
33ce0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 k(sqlite3*, int(
33cf0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
33d00 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
33d10 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 _rollback_hook(s
33d20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 qlite3*, void(*)
33d30 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 (void *), void*)
33d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33d50 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e F: Data Change N
33d60 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
33d70 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
33d80 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
33d90 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
33da0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
33db0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
33dc0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
33dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
33de0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
33df0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
33e00 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
33e10 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
33e20 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
33e30 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
33e40 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 d..** ^Any callb
33e50 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
33e60 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
33e70 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 is function.** f
33e80 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
33e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
33ea0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
33eb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
33ec0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
33ed0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 ointer to the fu
33ee0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 nction to invoke
33ef0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 when a.** row i
33f00 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
33f10 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
33f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
33f30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
33f40 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
33f50 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 of the third ar
33f60 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
33f70 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
33f80 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f ()..** ^The seco
33f90 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
33fa0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
33fb0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
33fc0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
33fd0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
33fe0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
33ff0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
34000 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
34010 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
34020 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
34030 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 ^The third and
34040 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
34050 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
34060 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
34070 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
34080 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e base and table n
34090 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ame containing t
340a0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e he affected row.
340b0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 .** ^The final c
340c0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
340d0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
340e0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
340f0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 ^In the case of
34100 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 an update, this
34110 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 is the [rowid] a
34120 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 fter the update
34130 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a takes place..**.
34140 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 ** ^(The update
34150 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f hook is not invo
34160 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
34170 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 l system tables
34180 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 are.** modified
34190 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 (i.e. sqlite_mas
341a0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 ter and sqlite_s
341b0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a equence).)^.**.*
341c0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e * ^In the curren
341d0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
341e0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f , the update hoo
341f0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f k.** is not invo
34200 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 ked when duplica
34210 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 tion rows are de
34220 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 leted because of
34230 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c an.** [ON CONFL
34240 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 ICT | ON CONFLIC
34250 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 T REPLACE] claus
34260 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 e. ^Nor is the
34270 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
34280 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 nvoked when rows
34290 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 are deleted usi
342a0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 ng the [truncate
342b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a optimization]..
342c0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e ** The exception
342d0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 s defined in thi
342e0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 s paragraph migh
342f0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 t change in a fu
34300 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
34310 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
34320 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
34330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34340 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
34350 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
34360 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
34370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34380 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
34390 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 e update hook.
343a0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
343b0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
343c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
343d0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
343e0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
343f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
34400 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
34410 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
34420 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
34430 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 update hook..**
34440 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
34450 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
34460 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
34470 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
34480 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
34490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
344a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
344b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
344c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
344d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
344e0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
344f0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a C,P) function.**
34500 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 returns the P a
34510 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
34520 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a previous call.*
34530 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
34540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34550 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
34560 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
34570 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a call on D..**.**
34580 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
34590 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
345a0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ok()] and [sqlit
345b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
345c0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
345d0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 s..*/.void *sqli
345e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
345f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
34600 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 void(*)(void *,i
34610 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a nt ,char const *
34620 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 ,char const *,sq
34630 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 lite3_int64),.
34640 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*.);../*.**
34650 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
34660 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 Or Disable Shar
34670 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a ed Pager Cache.*
34680 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 * KEYWORDS: {sha
34690 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a red cache}.**.**
346a0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
346b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
346c0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 les the sharing
346d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
346e0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 cache.** and sch
346f0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 ema data structu
34700 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 res between [dat
34710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34720 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a | connections].
34730 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 ** to the same d
34740 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 atabase. Sharing
34750 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
34760 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 he argument is t
34770 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 rue.** and disab
34780 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
34790 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a ent is false.)^.
347a0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 **.** ^Cache sha
347b0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 ring is enabled
347c0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 and disabled for
347d0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 an entire proce
347e0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 ss..** This is a
347f0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 change as of SQ
34800 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
34810 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 .0. In prior ver
34820 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c sions of SQLite,
34830 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 .** sharing was
34840 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
34850 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 led for each thr
34860 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ead separately..
34870 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 **.** ^(The cach
34880 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 e sharing mode s
34890 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 et by this inter
348a0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c face effects all
348b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 subsequent.** c
348c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
348d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
348e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 e3_open_v2()], a
348f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
34900 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 16()]..** Existi
34910 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ng database conn
34920 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 ections continue
34930 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 use the sharing
34940 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 mode.** that wa
34950 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 s in effect at t
34960 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 he time they wer
34970 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a e opened.)^.**.*
34980 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
34990 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
349a0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
349b0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
349c0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
349d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
349e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
349f0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
34a00 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 wise.)^.**.** ^S
34a10 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
34a20 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
34a30 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
34a40 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
34a50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
34a60 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
34a70 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
34a80 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
34a90 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
34aa0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
34ab0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
34ac0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
34ad0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
34ae0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 Mode].*/.int sq
34af0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
34b00 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a red_cache(int);.
34b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34b20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 Attempt To Free
34b30 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a Heap Memory.**.
34b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34b50 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
34b60 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
34b70 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 pts to free N by
34b80 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d tes.** of heap m
34b90 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 emory by dealloc
34ba0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 ating non-essent
34bb0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ial memory alloc
34bc0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 ations.** held b
34bd0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c y the database l
34be0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 ibrary. Memory
34bf0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 used to cache d
34c00 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 atabase.** pages
34c10 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 to improve perf
34c20 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 ormance is an ex
34c30 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 ample of non-ess
34c40 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a ential memory..*
34c50 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * ^sqlite3_relea
34c60 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 se_memory() retu
34c70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
34c80 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 f bytes actually
34c90 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 freed,.** which
34ca0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
34cb0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 r less than the
34cc0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
34cd0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
34ce0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
34cf0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
34d00 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 no-op returning
34d10 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 zero.** if SQLit
34d20 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 e is not compile
34d30 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 d with [SQLITE_E
34d40 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e NABLE_MEMORY_MAN
34d50 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 AGEMENT]..*/.int
34d60 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
34d70 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f _memory(int);../
34d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
34d90 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e mpose A Limit On
34da0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a Heap Size.**.**
34db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f ^The sqlite3_so
34dc0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
34dd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
34de0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 and/or queries
34df0 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 the.** soft limi
34e00 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 t on the amount
34e10 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 of heap memory t
34e20 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 hat may be alloc
34e30 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a ated by SQLite..
34e40 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 ** ^SQLite striv
34e50 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 es to keep heap
34e60 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 memory utilizati
34e70 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 on below the sof
34e80 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 t heap.** limit
34e90 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 by reducing the
34ea0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
34eb0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 held in the page
34ec0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 cache.** as hea
34ed0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 p memory usages
34ee0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c approaches the l
34ef0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f imit..** ^The so
34f00 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
34f10 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 "soft" because
34f20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 even though SQLi
34f30 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 te strives to st
34f40 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 ay.** below the
34f50 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 limit, it will e
34f60 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 xceed the limit
34f70 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 rather than gene
34f80 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 rate.** an [SQLI
34f90 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e TE_NOMEM] error.
34fa0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
34fb0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
34fc0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 limit .** is adv
34fd0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a isory only..**.*
34fe0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 * ^The return va
34ff0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
35000 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
35010 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 64() is the size
35020 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 of.** the soft
35030 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 heap limit prior
35040 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e to the call. ^
35050 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
35060 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a N is negative.**
35070 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 then no change
35080 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 is made to the s
35090 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 oft heap limit.
350a0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 Hence, the curr
350b0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 ent.** size of t
350c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
350d0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d it can be determ
350e0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 ined by invoking
350f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 .** sqlite3_soft
35100 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 _heap_limit64()
35110 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 with a negative
35120 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
35130 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 ^If the argument
35140 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 N is zero then
35150 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
35160 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e mit is disabled.
35170 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 .**.** ^(The sof
35180 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
35190 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 not enforced in
351a0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c the current impl
351b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 ementation.** if
351c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
351d0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 following condit
351e0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a ions are true:.*
351f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
35200 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 > The soft heap
35210 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 limit is set to
35220 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 zero..** <li> Me
35230 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 mory accounting
35240 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e is disabled usin
35250 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 g a combination
35260 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b of the.** [
35270 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
35280 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
35290 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 EMSTATUS],...) s
352a0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e tart-time option
352b0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 and.** the
352c0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
352d0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 _MEMSTATUS] comp
352e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
352f0 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 .** <li> An alte
35300 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 rnative page cac
35310 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
35320 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75 n is specified u
35330 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 sing.** [sq
35340 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
35350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
35360 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c CHE],...)..** <l
35370 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 i> The page cach
35380 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d e allocates from
35390 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 its own memory
353a0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a pool supplied.**
353b0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 by [sqlite
353c0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
353d0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
353e0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 HE],...) rather
353f0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f than.** fro
35400 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c m the heap..** <
35410 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 /ul>)^.**.** Beg
35420 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 inning with SQLi
35430 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 te version 3.7.3
35440 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
35450 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 limit is enforce
35460 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 d.** regardless
35470 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
35480 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e t the [SQLITE_EN
35490 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
354a0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 GEMENT].** compi
354b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
354c0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 s invoked. With
354d0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
354e0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
354f0 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 T],.** the soft
35500 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e heap limit is en
35510 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 forced on every
35520 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
35530 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b n. Without.** [
35540 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
35550 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d MORY_MANAGEMENT]
35560 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
35570 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e limit is only en
35580 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d forced.** when m
35590 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 emory is allocat
355a0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 ed by the page c
355b0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 ache. Testing s
355c0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 uggests that bec
355d0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 ause.** the page
355e0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 cache is the pr
355f0 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 edominate memory
35600 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c user in SQLite,
35610 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 most.** applica
35620 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 tions will achie
35630 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 ve adequate soft
35640 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f heap limit enfo
35650 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a rcement without.
35660 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 ** the use of [S
35670 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
35680 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e ORY_MANAGEMENT].
35690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 .**.** The circu
356a0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 mstances under w
356b0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c hich SQLite will
356c0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 enforce the sof
356d0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 t heap limit may
356e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 .** changes in f
356f0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
35700 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c f SQLite..*/.sql
35710 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
35720 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
35730 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 it64(sqlite3_int
35740 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 64 N);../*.** CA
35750 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
35760 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d ed Soft Heap Lim
35770 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 it Interface.**
35780 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
35790 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 This is a depre
357a0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 cated version of
357b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f the [sqlite3_so
357c0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
357d0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
357e0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 This routine i
357f0 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 s provided for h
35800 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
35810 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e ibility.** only.
35820 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 All new applic
35830 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 ations should us
35840 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
35850 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
35860 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 t64()] interface
35870 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 rather than thi
35880 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 s one..*/.SQLITE
35890 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
358a0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 sqlite3_soft_he
358b0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b ap_limit(int N);
358c0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
358d0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 F: Extract Metad
358e0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 ata About A Colu
358f0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a mn Of A Table.**
35900 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
35910 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 e returns metada
35920 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 ta about a speci
35930 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 fic column of a
35940 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 specific.** data
35950 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 base table acces
35960 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 sible using the
35970 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
35980 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
35990 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
359a0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 rst function arg
359b0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
359c0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e e column is iden
359d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 tified by the se
359e0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 cond, third and
359f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
35a00 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e s to.** this fun
35a10 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f ction. ^The seco
35a20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
35a30 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 either the name
35a40 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
35a50 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c ** (i.e. "main",
35a60 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 "temp", or an a
35a70 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
35a80 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
35a90 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 specified.** ta
35aa0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 ble or NULL. ^If
35ab0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 it is NULL, the
35ac0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 n all attached d
35ad0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 atabases are sea
35ae0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 rched.** for the
35af0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 table using the
35b00 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
35b10 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 used by the data
35b20 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a base engine to.*
35b30 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c * resolve unqual
35b40 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 ified table refe
35b50 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rences..**.** ^T
35b60 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
35b70 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
35b80 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 o this function
35b90 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e are the table an
35ba0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 d column.** name
35bb0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 of the desired
35bc0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 column, respecti
35bd0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 vely. Neither of
35be0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
35bf0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c s.** may be NULL
35c00 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 ..**.** ^Metadat
35c10 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 a is returned by
35c20 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 writing to the
35c30 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 memory locations
35c40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 passed as the 5
35c50 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 th.** and subseq
35c60 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 uent parameters
35c70 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
35c80 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 . ^Any of these
35c90 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 arguments may be
35ca0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 .** NULL, in whi
35cb0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 ch case the corr
35cc0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e esponding elemen
35cd0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 t of metadata is
35ce0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 omitted..**.**
35cf0 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ^(<blockquote>.*
35d00 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
35d10 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
35d20 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
35d30 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
35d40 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
35d50 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
35d60 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
35d70 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
35d80 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
35d90 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
35da0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
35db0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
35dc0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
35dd0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
35de0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
35df0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
35e00 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
35e10 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
35e20 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
35e30 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
35e40 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
35e50 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
35e60 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
35e70 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
35e80 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
35e90 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
35ea0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 is [AUTOINCREME
35eb0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a NT].** </table>.
35ec0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
35ed0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 )^.**.** ^The me
35ee0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 mory pointed to
35ef0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 by the character
35f00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
35f10 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 ed for the.** de
35f20 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 claration type a
35f30 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 nd collation seq
35f40 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f uence is valid o
35f50 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 nly until the ne
35f60 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e xt.** call to an
35f70 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e y SQLite API fun
35f80 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ction..**.** ^If
35f90 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 the specified t
35fa0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 able is actually
35fb0 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 a view, an [err
35fc0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
35fd0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 rned..**.** ^If
35fe0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f the specified co
35ff0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c lumn is "rowid",
36000 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 "oid" or "_rowi
36010 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 d_" and an.** [I
36020 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
36030 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 EY] column has b
36040 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 een explicitly d
36050 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 eclared, then th
36060 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
36070 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 meters are set f
36080 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c or the explicitl
36090 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
360a0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 n. ^(If there is
360b0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
360c0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 y declared [INTE
360d0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
360e0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
360f0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
36100 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
36110 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
36120 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
36130 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
36140 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
36150 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
36160 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
36170 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
36180 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
36190 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
361a0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
361b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 e>)^.**.** ^(Thi
361c0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c s function may l
361d0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 oad one or more
361e0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 schemas from dat
361f0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 abase files. If
36200 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 an.** error occu
36210 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 rs during this p
36220 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 rocess, or if th
36230 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c e requested tabl
36240 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 e or column.** c
36250 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 annot be found,
36260 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
36270 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
36280 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
36290 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 left.** in the
362a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
362b0 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 tion] (to be ret
362c0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c rieved using sql
362d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 ite3_errmsg()).)
362e0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 ^.**.** ^This AP
362f0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
36300 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
36310 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
36320 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
36330 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
36340 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
36350 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
36360 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e l defined..*/.in
36370 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
36380 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
36390 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
363a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
363b0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
363c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
363d0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
363e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
363f0 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
36400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
36410 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
36420 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
36430 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
36440 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
36450 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
36460 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
36470 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
36480 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
36490 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
364a0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
364b0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
364c0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
364d0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
364e0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
364f0 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
36500 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
36510 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
36520 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
36530 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
36540 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
36550 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
36560 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
36570 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
36580 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
36590 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
365a0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
365b0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
365c0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
365d0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
365e0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a Extension.**.**
365f0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
36600 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 loads an SQLite
36610 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 extension libra
36620 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 ry from the name
36630 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d file..**.** ^T
36640 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
36650 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
36660 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
36670 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c o load an.** SQL
36680 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
36690 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 brary contained
366a0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c in the file zFil
366b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e e..**.** ^The en
366c0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
366d0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 oc..** ^zProc ma
366e0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 y be 0, in which
366f0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f case the name o
36700 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e f the entry poin
36710 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f t.** defaults to
36720 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 "sqlite3_extens
36730 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 ion_init"..** ^T
36740 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f he sqlite3_load_
36750 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 extension() inte
36760 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
36770 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
36780 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
36790 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
367a0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
367b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 ng..** ^If an er
367c0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
367d0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
367e0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 , then the.** [s
367f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
36800 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 nsion()] interfa
36810 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 ce shall attempt
36820 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 to.** fill *pzE
36830 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 rrMsg with error
36840 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 message text st
36850 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a ored in memory.*
36860 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
36870 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
36880 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 )]. The calling
36890 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 function.** shou
368a0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d ld free this mem
368b0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ory by calling [
368c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
368d0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f .**.** ^Extensio
368e0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 n loading must b
368f0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a e enabled using.
36900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 ** [sqlite3_enab
36910 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
36920 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 n()] prior to ca
36930 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a lling this API,.
36940 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
36950 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
36960 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 turned..**.** Se
36970 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 e also the [load
36980 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c _extension() SQL
36990 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 function]..*/.i
369a0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f nt sqlite3_load_
369b0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c extension(. sql
369c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
369d0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 /* Load the e
369e0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 xtension into th
369f0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e is database conn
36a00 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ection */. cons
36a10 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 t char *zFile,
36a20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
36a30 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 shared library
36a40 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e containing exten
36a50 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 sion */. const
36a60 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 char *zProc,
36a70 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 /* Entry point.
36a80 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 Derived from zF
36a90 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 ile if 0 */. ch
36aa0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 ar **pzErrMsg
36ab0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 /* Put error
36ac0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 message here if
36ad0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a not 0 */.);../*
36ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
36af0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
36b00 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
36b10 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e g.**.** ^So as n
36b20 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 ot to open secur
36b30 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 ity holes in old
36b40 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 er applications
36b50 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 that are.** unpr
36b60 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 epared to deal w
36b70 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f ith extension lo
36b80 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 ading, and as a
36b90 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 means of disabli
36ba0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 ng.** extension
36bb0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 loading while ev
36bc0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e aluating user-en
36bd0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 tered SQL, the f
36be0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 ollowing API.**
36bf0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 is provided to t
36c00 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 urn the [sqlite3
36c10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
36c20 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 )] mechanism on
36c30 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e and off..**.** ^
36c40 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
36c50 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 g is off by defa
36c60 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 ult. See ticket
36c70 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 #1863..** ^Call
36c80 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 the sqlite3_enab
36c90 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
36ca0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 n() routine with
36cb0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 onoff==1.** to
36cc0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
36cd0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
36ce0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
36cf0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 ==0 to turn.** i
36d00 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
36d10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
36d20 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
36d30 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a ension(sqlite3 *
36d40 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a db, int onoff);.
36d50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36d60 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c Automatically L
36d70 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c oad Statically L
36d80 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 inked Extensions
36d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
36da0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
36db0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 e xEntryPoint()
36dc0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
36dd0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 nvoked for.** ea
36de0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 ch new [database
36df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
36e00 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 t is created. T
36e10 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 he idea here is
36e20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f that.** xEntryPo
36e30 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 int() is the ent
36e40 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 ry point for a s
36e50 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 tatically linked
36e60 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f SQLite extensio
36e70 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 n.** that is to
36e80 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
36e90 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c loaded into all
36ea0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
36eb0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
36ec0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 ^(Even though t
36ed0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 he function prot
36ee0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 otype shows that
36ef0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 xEntryPoint() t
36f00 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d akes.** no argum
36f10 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 ents and returns
36f20 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e void, SQLite in
36f30 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e vokes xEntryPoin
36f40 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a t() with three.*
36f50 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 * arguments and
36f60 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 expects and inte
36f70 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 ger result as if
36f80 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f the signature o
36f90 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 f the.** entry p
36fa0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f oint where as fo
36fb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
36fc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
36fd0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 * int xE
36fe0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e ntryPoint(.** &n
36ff0 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 bsp; sqlite3
37000 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 *db,.**
37010 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
37020 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 zErrMsg,.** &nbs
37030 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 p; const stru
37040 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 ct sqlite3_api_r
37050 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a outines *pThunk.
37060 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a ** );.**
37070 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
37080 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 ote>)^.**.** If
37090 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 the xEntryPoint
370a0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 routine encounte
370b0 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 rs an error, it
370c0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 should make *pzE
370d0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 rrMsg.** point t
370e0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 o an appropriate
370f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 error message (
37100 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
37110 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
37120 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e ]).** and return
37130 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
37140 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e [error code]. ^
37150 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 SQLite ensures t
37160 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a hat *pzErrMsg.**
37170 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 is NULL before
37180 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 calling the xEnt
37190 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c ryPoint(). ^SQL
371a0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a ite will invoke.
371b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
371c0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 ()] on *pzErrMsg
371d0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 after xEntryPoi
371e0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e nt() returns. ^
371f0 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 If any.** xEntry
37200 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 Point() returns
37210 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 an error, the [s
37220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
37230 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
37240 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
37250 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 e3_open_v2()] ca
37260 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 ll that provoked
37270 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 the xEntryPoint
37280 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a () will fail..**
37290 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
372a0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 ite3_auto_extens
372b0 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 ion(X) with an e
372c0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 ntry point X tha
372d0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 t is already.**
372e0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 on the list of a
372f0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
37300 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ons is a harmles
37310 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 s no-op. ^No ent
37320 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c ry point.** will
37330 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 be called more
37340 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 than once for ea
37350 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
37360 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f ection that is o
37370 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 pened..**.** See
37380 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
37390 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
373a0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 sion()]..*/.int
373b0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 sqlite3_auto_ext
373c0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 ension(void (*xE
373d0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 ntryPoint)(void)
373e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
373f0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 EF: Reset Automa
37400 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f tic Extension Lo
37410 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ading.**.** ^Thi
37420 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 s interface disa
37430 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 bles all automat
37440 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 ic extensions pr
37450 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 eviously.** regi
37460 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 stered using [sq
37470 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
37480 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 sion()]..*/.void
37490 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 sqlite3_reset_a
374a0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
374b0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 id);../*.** The
374c0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 interface to the
374d0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
374e0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 echanism is curr
374f0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
37500 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
37510 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
37520 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
37530 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
37540 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
37550 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
37560 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
37570 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
37580 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
37590 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
375a0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
375b0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
375c0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
375d0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
375e0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
375f0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
37600 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
37610 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
37620 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 /../*.** Structu
37630 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 res used by the
37640 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e virtual table in
37650 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 terface.*/.typed
37660 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
37670 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 3_vtab sqlite3_v
37680 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 tab;.typedef str
37690 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
376a0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 x_info sqlite3_i
376b0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 ndex_info;.typed
376c0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
376d0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 3_vtab_cursor sq
376e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
376f0 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 r;.typedef struc
37700 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
37710 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b sqlite3_module;
37720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37730 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
37740 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
37750 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 DS: sqlite3_modu
37760 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c le {virtual tabl
37770 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 e module}.**.**
37780 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 This structure,
37790 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 sometimes called
377a0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c a "virtual tabl
377b0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 e module", .** d
377c0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 efines the imple
377d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b mentation of a [
377e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e virtual tables].
377f0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 .** This struc
37800 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f ture consists mo
37810 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 stly of methods
37820 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a for the module..
37830 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c **.** ^A virtual
37840 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 table module is
37850 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c created by fill
37860 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 ing in a persist
37870 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 ent.** instance
37880 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
37890 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 e and passing a
378a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
378b0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b instance.** to [
378c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
378d0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c odule()] or [sql
378e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
378f0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 le_v2()]..** ^Th
37900 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 e registration r
37910 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 emains valid unt
37920 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 il it is replace
37930 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 d by a different
37940 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e .** module or un
37950 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 til the [databas
37960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c e connection] cl
37970 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 oses. The conte
37980 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 nt.** of this st
37990 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 ructure must not
379a0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 change while it
379b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 is registered w
379c0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 ith.** any datab
379d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a ase connection..
379e0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
379f0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 3_module {. int
37a00 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
37a10 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 (*xCreate)(sqli
37a20 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 te3*, void *pAux
37a30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
37a40 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 int argc, const
37a50 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 char *const*arg
37a60 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 v,.
37a70 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
37a80 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 *ppVTab, char**)
37a90 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 ;. int (*xConne
37aa0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ct)(sqlite3*, vo
37ab0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 id *pAux,.
37ac0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
37ad0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 c, const char *c
37ae0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 onst*argv,.
37af0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
37b00 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 3_vtab **ppVTab,
37b10 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 char**);. int
37b20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 (*xBestIndex)(sq
37b30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
37b40 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 b, sqlite3_index
37b50 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 _info*);. int (
37b60 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 *xDisconnect)(sq
37b70 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
37b80 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 b);. int (*xDes
37b90 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 troy)(sqlite3_vt
37ba0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
37bb0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
37bc0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 e3_vtab *pVTab,
37bd0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
37be0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b sor **ppCursor);
37bf0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
37c00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
37c10 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
37c20 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 xFilter)(sqlite3
37c30 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 _vtab_cursor*, i
37c40 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 nt idxNum, const
37c50 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 char *idxStr,.
37c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
37c70 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 nt argc, sqlite3
37c80 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a _value **argv);.
37c90 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 int (*xNext)(s
37ca0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
37cb0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 or*);. int (*xE
37cc0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 of)(sqlite3_vtab
37cd0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 _cursor*);. int
37ce0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 (*xColumn)(sqli
37cf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
37d00 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 , sqlite3_contex
37d10 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 t*, int);. int
37d20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 (*xRowid)(sqlite
37d30 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
37d40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
37d50 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a Rowid);. int (*
37d60 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 xUpdate)(sqlite3
37d70 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 _vtab *, int, sq
37d80 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 lite3_value **,
37d90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 sqlite3_int64 *)
37da0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e ;. int (*xBegin
37db0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
37dc0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
37dd0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 xSync)(sqlite3_v
37de0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
37df0 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 nt (*xCommit)(sq
37e00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
37e10 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c b);. int (*xRol
37e20 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 lback)(sqlite3_v
37e30 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
37e40 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 nt (*xFindFuncti
37e50 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 on)(sqlite3_vtab
37e60 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 *pVtab, int nAr
37e70 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a g, const char *z
37e80 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 Name,.
37e90 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
37ea0 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c d (**pxFunc)(sql
37eb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
37ec0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
37ed0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 *),.
37ee0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 void
37ef0 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 **ppArg);. int
37f00 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 (*xRename)(sqlit
37f10 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 e3_vtab *pVtab,
37f20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 const char *zNew
37f30 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68 );. /* The meth
37f40 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
37f50 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
37f60 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20 e sqlite_module
37f70 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20 object. Those .
37f80 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f ** below are fo
37f90 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 r version 2 and
37fa0 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e greater. */. in
37fb0 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 t (*xSavepoint)(
37fc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
37fd0 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 Tab, int);. int
37fe0 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c (*xRelease)(sql
37ff0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
38000 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
38010 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c xRollbackTo)(sql
38020 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
38030 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a , int);.};../*.*
38040 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
38050 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 ual Table Indexi
38060 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ng Information.*
38070 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
38080 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a te3_index_info.*
38090 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
380a0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 _index_info stru
380b0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 cture and its su
380c0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 bstructures is u
380d0 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f sed as part.** o
380e0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 f the [virtual t
380f0 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 able] interface
38100 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 to.** pass infor
38110 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
38120 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c receive the repl
38130 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 y from the [xBes
38140 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f tIndex].** metho
38150 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 d of a [virtual
38160 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
38170 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 The fields under
38180 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 **Inputs** are
38190 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f the.** inputs to
381a0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 xBestIndex and
381b0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 are read-only.
381c0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 xBestIndex inser
381d0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 ts its.** result
381e0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 s into the **Out
381f0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a puts** fields..*
38200 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 *.** ^(The aCons
38210 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 traint[] array r
38220 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 ecords WHERE cla
38230 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
38240 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a of the form:.**.
38250 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 ** <blockquote>c
38260 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 olumn OP expr</b
38270 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
38280 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 where OP is =,
38290 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 <, <=, >
382a0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 ;, or >=.)^
382b0 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 ^(The particular
382c0 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 operator is.**
382d0 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 stored in aConst
382e0 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 raint[].op using
382f0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b one of the.** [
38300 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
38310 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c STRAINT_EQ | SQL
38320 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
38330 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e AINT_ values].)^
38340 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 .** ^(The index
38350 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 of the column is
38360 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 stored in.** aC
38370 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c onstraint[].iCol
38380 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 umn.)^ ^(aConst
38390 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 raint[].usable i
383a0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a s TRUE if the.**
383b0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 expr on the rig
383c0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e ht-hand side can
383d0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 be evaluated (a
383e0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 nd thus the cons
383f0 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 traint.** is usa
38400 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 ble) and false i
38410 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a f it cannot.)^.*
38420 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 *.** ^The optimi
38430 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c zer automaticall
38440 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 y inverts terms
38450 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 of the form "exp
38460 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 r OP column".**
38470 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 and makes other
38480 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 simplifications
38490 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 to the WHERE cla
384a0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 use in an attemp
384b0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d t to.** get as m
384c0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 any WHERE clause
384d0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 terms into the
384e0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 form shown above
384f0 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a as possible..**
38500 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e ^The aConstrain
38510 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 t[] array only r
38520 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 eports WHERE cla
38530 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 use terms that a
38540 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 re.** relevant t
38550 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 o the particular
38560 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 virtual table b
38570 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a eing queried..**
38580 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e .** ^Information
38590 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 about the ORDER
385a0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 BY clause is st
385b0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 ored in aOrderBy
385c0 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 []..** ^Each ter
385d0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
385e0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
385f0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
38600 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
38610 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 [xBestIndex] me
38620 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 thod must fill a
38630 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
38640 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 ] with informati
38650 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 on.** about what
38660 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 parameters to p
38670 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 ass to xFilter.
38680 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 ^If argvIndex>0
38690 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 then.** the rig
386a0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ht-hand side of
386b0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
386c0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 g aConstraint[]
386d0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 is evaluated.**
386e0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 and becomes the
386f0 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 argvIndex-th ent
38700 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 ry in argv. ^(I
38710 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 f aConstraintUsa
38720 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 ge[].omit.** is
38730 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 true, then the c
38740 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 onstraint is ass
38750 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 umed to be fully
38760 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a handled by the.
38770 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ** virtual table
38780 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 and is not chec
38790 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c ked again by SQL
387a0 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ite.)^.**.** ^Th
387b0 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
387c0 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
387d0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
387e0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b ed into the.** [
387f0 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e xFilter] method.
38800 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 .** ^[sqlite3_fr
38810 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f ee()] is used to
38820 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 free idxPtr if
38830 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e and only if.** n
38840 65 65 6