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: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 ough to the 1st
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 ocation. ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 ipped. ^If the
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ning..**.** ^If
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ns SQLITE_ABORT
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 ult. ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e . ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 lback is a NULL
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 pointer. ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 ntry represents
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 s are evaluated
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c ** is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 ent text passed
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 into.** the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
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 20 20 20 2f 2a 20 /*
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
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 20 20 20 2f 2a 20 /*
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **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 20 20 20 2f 2a 20 45 72 72 6f /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a result codes],.
3e40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 ** [sqlite3_vtab
3e50: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 _on_conflict()]
3e60: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b [SQLITE_ROLLBACK
3e70: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d | result codes]
3e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
3e90: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
3ea0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
3eb0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
3ec0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
3ed0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
3ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
3ef0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
3f00: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
3f10: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
3f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f30: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
3f40: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
3f50: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
3f60: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3f70: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
3f80: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
3f90: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3fb0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
3fc0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
3fd0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
3fe0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
3ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
4000: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
4010: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4020: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4040: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
4050: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
4060: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
4070: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
4080: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
4090: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
40a0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
40c0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
40d0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
40e0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
40f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4100: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
4110: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4120: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4130: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4140: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4160: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
4170: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
4180: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
4190: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
41a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
41b0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
41c0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
41d0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
41e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
41f0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
4200: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 /* Unknown opc
4210: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 ode in sqlite3_f
4220: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f ile_control() */
4230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4240: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
4250: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
4260: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
4270: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
4280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4290: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
42a0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
42b0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
42c0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
42d0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
42e0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 15 /* Datab
42f0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f ase lock protoco
4300: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 l error */.#defi
4310: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 ne SQLITE_EMPTY
4320: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 16 /* Da
4330: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 tabase is empty
4340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4350: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 E_SCHEMA 17
4360: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4370: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
4380: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4390: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 ITE_TOOBIG
43a0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 18 /* String o
43b0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 r BLOB exceeds s
43c0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 ize limit */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
43e0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 TRAINT 19 /*
43f0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e Abort due to con
4400: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
4410: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
4420: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
4430: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
4440: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 e mismatch */.#d
4450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 efine SQLITE_MIS
4460: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a USE 21 /*
4470: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e Library used in
4480: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 correctly */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 fine SQLITE_NOLF
44a0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 S 22 /*
44b0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 Uses OS features
44c0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f not supported o
44d0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e n host */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 e SQLITE_AUTH
44f0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 23 /* Aut
4500: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 horization denie
4510: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4520: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 ITE_FORMAT
4530: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 24 /* Auxiliar
4540: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 y database forma
4550: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 t error */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 ne SQLITE_RANGE
4570: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 25 /* 2n
4580: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
4590: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 qlite3_bind out
45a0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 of range */.#def
45b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 ine SQLITE_NOTAD
45c0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 B 26 /* F
45d0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 ile opened that
45e0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
45f0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4600: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
4610: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
4620: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4630: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
4640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4650: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
4660: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
4670: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
4680: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
4690: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
46a0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
46b0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
46c0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
46d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
46e0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
46f0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 de} {extended er
4700: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
4710: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
4720: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b d result code} {
4730: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4740: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 codes}.**.** In
4750: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4760: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4770: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4780: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 eturn one of 26
4790: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
47a0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
47b0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c odes]. However,
47c0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 experience has
47d0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 shown that many
47e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 of.** these resu
47f0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f lt codes are too
4800: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e coarse-grained.
4810: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 They do not pr
4820: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 ovide as.** much
4830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
4840: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 ut problems as p
4850: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
4860: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 like. In an ef
4870: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 fort to.** addre
4880: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 ss this, newer v
4890: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
48a0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 e (version 3.3.8
48b0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c and later) incl
48c0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 ude.** support f
48d0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 or additional re
48e0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 sult codes that
48f0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 provide more det
4900: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f ailed informatio
4910: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 n.** about error
4920: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 s. The extended
4930: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4940: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
4950: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 bled.** on a per
4960: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4970: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 tion basis using
4980: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4990: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
49a0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a _codes()] API..*
49b0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 *.** Some of the
49c0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e available exten
49d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
49e0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 are listed here
49f0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 ..** One may exp
4a00: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ect the number o
4a10: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c f extended resul
4a20: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 t codes will be
4a30: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 expand.** over t
4a40: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ime. Software t
4a50: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 hat uses extende
4a60: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 d result codes s
4a70: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 hould expect.**
4a80: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c to see new resul
4a90: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 t codes in futur
4aa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
4ab0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
4ac0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 SQLITE_OK result
4ad0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 code will never
4ae0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 be extended. I
4af0: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a t will always.**
4b00: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f be exactly zero
4b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
4b20: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4b40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
4b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4b60: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
4b70: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
4b80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
4b90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4ba0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
4bb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4bc0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
4bd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4be0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
4bf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4c00: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
4c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c20: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4c40: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4c60: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
4c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4c80: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4ca0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
4cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4cc0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
4cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4ce0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
4cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4d00: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
4d10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4d20: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
4d30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4d40: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
4d50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4d60: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
4d70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4d80: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
4d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4da0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
4db0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4dc0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
4dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4de0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
4df0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4e00: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
4e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4e20: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
4e30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4e40: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
4e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4e60: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
4e70: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
4e80: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
4e90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4ea0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
4eb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4ec0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
4ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4ee0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
4ef0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4f00: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
4f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4f20: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
4f30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4f40: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
4f50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4f60: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
4f70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4f80: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
4f90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4fa0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
4fb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4fc0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
4fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4fe0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
4ff0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5000: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5020: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5030: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5040: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5060: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
5070: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5080: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
5090: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
50a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
50b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
50c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
50d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
50e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
50f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5100: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
5110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
5120: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 TOPEN_NOTEMPDIR
5130: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
5140: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a TOPEN | (1<<8)).
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5160: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
5170: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
5180: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
51a0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
51b0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
51c0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
51d0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 <8))../*.** CAPI
51e0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 3REF: Flags For
51f0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 File Open Operat
5200: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
5210: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
5220: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
5230: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
5240: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
5250: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
5260: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
5270: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
5290: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 xOpen method of
52a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
52b0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
52e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
52f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5300: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5320: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
5330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
5340: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5350: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5370: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
5380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5390: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
53a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
53d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
53e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5400: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
5420: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5440: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
5450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
5460: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5480: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
54a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
54b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
54d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
54e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5500: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
5510: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
5520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5540: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
5550: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
5560: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5580: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
5590: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
55a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
55c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
55d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
55e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5600: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
5610: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
5620: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5640: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
5650: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
5660: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5670: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5690: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
56a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
56b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
56c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
56d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
56e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
56f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
5700: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5710: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5730: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
5740: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
5750: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5760: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5780: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
5790: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
57a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
57c0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
57d0: 20 20 20 20 20 20 30 78 30 30 31 30 30 30 30 30 0x00100000
57e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
57f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5800: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
5810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5820: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
5830: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
5840: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
5850: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
5860: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
5870: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
5880: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
5890: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
58a0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
58b0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
58c0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
58d0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 of the these.**
58e0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
58f0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
5900: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
5910: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
5920: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
5930: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
5940: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5950: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
5960: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
5970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5980: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
5990: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
59a0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
59b0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
59c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
59d0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
59e0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
59f0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
5a00: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
5a10: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
5a20: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
5a30: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
5a40: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
5a50: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
5a60: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
5a70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5a80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
5a90: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
5aa0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
5ab0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
5ac0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
5ad0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
5ae0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
5af0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
5b00: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
5b10: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
5b20: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
5b30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
5b40: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
5b50: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
5b60: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5b70: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5b80: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5b90: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5ba0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 e()..*/.#define
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5bc0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
5bd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
5be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5bf0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
5c00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5c10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
5c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5c30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
5c40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5c60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
5c70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5c80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
5c90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
5ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
5cb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
5cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5cd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
5ce0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
5cf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5d00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
5d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
5d20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
5d30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5d40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
5d50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5d70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5d90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
5da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
5db0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
5dc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
5dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5de0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
5df0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5e00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
5e10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
5e20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
5e30: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 0x00000800../*.
5e40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
5e50: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
5e60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
5e70: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 es one of these
5e80: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
5e90: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
5ea0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
5eb0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 s it makes to th
5ec0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 e xLock() and xU
5ed0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a nlock() methods.
5ee0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 ** of an [sqlite
5ef0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
5f00: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
5f10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e SQLITE_LOCK_NON
5f20: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 E 0.#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5f40: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 _SHARED 1
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5f60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 LOCK_RESERVED
5f70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
5f80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
5f90: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
5fa0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 SQLITE_LOCK_EXC
5fb0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a LUSIVE 4../*
5fc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 .** CAPI3REF: Sy
5fd0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 nchronization Ty
5fe0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 pe Flags.**.** W
5ff0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
6000: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d es the xSync() m
6010: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b ethod of an.** [
6020: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6030: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 ds] object it us
6040: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e es a combination
6050: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 of.** these int
6060: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
6070: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
6080: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 nt..**.** When t
6090: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 he SQLITE_SYNC_D
60a0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 ATAONLY flag is
60b0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 used, it means t
60c0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 hat the.** sync
60d0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e operation only n
60e0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 eeds to flush da
60f0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 ta to mass stora
6100: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e ge. Inode.** in
6110: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e formation need n
6120: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 ot be flushed. I
6130: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 f the lower four
6140: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 bits of the fla
6150: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 g.** equal SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 E_SYNC_NORMAL, t
6170: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 hat means to use
6180: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 normal fsync()
6190: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 semantics..** If
61a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
61b0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 bits equal SQLIT
61c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 E_SYNC_FULL, tha
61d0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 t means.** to us
61e0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 e Mac OS X style
61f0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 fullsync instea
6200: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a d of fsync()..**
6210: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 .** Do not confu
6220: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 se the SQLITE_SY
6230: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
6240: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 LITE_SYNC_FULL f
6250: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 lags.** with the
6260: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
6270: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 nous]=NORMAL and
6280: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
6290: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 nous]=FULL.** se
62a0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 ttings. The [sy
62b0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 nchronous pragma
62c0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 ] determines whe
62d0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a n calls to the.*
62e0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 * xSync VFS meth
62f0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 od occur and app
6300: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 lies uniformly a
6310: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f cross all platfo
6320: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 rms..** The SQLI
6330: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
6340: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
6350: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d ULL flags determ
6360: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 ine how.** energ
6370: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 etic or rigorous
6380: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 or forceful the
6390: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 sync operations
63a0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 are and.** only
63b0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e make a differen
63c0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f ce on Mac OSX fo
63d0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 r the default SQ
63e0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 Lite code..** (T
63f0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 hird-party VFS i
6400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
6410: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 ight also make t
6420: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a he distinction.*
6430: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 * between SQLITE
6440: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
6450: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
6460: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 L, but among the
6470: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 .** operating sy
6480: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 stems natively s
6490: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
64a0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 te, only Mac OSX
64b0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 .** cares about
64c0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 the difference.)
64d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
64e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 TE_SYNC_NORMAL
64f0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 0x00002.#d
6500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
6510: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 C_FULL
6520: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 0x00003.#define
6530: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
6540: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 ONLY 0x0001
6550: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
6560: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
6570: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
6580: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 .**.** An [sqlit
6590: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
65a0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
65b0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a en file in the .
65c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 ** [sqlite3_vfs
65d0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c | OS interface l
65e0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 ayer]. Individu
65f0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a al OS interface.
6600: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
6610: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
6620: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
6630: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
6640: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
6650: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
6660: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
6670: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
6680: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
6690: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
66a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
66b0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
66c0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
66d0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
66e0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
66f0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
6700: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
6710: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
6720: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
6730: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
6740: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
6750: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
6760: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
6770: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
6780: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
6790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
67a0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
67b0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
67c0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 Object.**.** Ev
67d0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 ery file opened
67e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
67f0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f vfs] xOpen metho
6800: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a d populates an.*
6810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
6820: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 object (or, mor
6830: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 e commonly, a su
6840: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
6850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
6860: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 object) with a p
6870: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
6880: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
6890: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ject..** This ob
68a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
68b0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
68c0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
68d0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
68e0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 gainst the open
68f0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 file represented
6900: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
6910: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a _file] object..*
6920: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 *.** If the xOpe
6930: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 n method sets th
6940: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
6950: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
6960: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
6970: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
6980: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
6990: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
69a0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
69b0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
69c0: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 he xOpen reporte
69d0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 d that it failed
69e0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 . The.** only w
69f0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ay to prevent a
6a00: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 call to xClose f
6a10: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 ollowing a faile
6a20: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f d xOpen.** is fo
6a30: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 r the xOpen to s
6a40: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
6a50: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
6a60: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a ment to NULL..**
6a70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
6a80: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 gument to xSync
6a90: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 may be one of [S
6aa0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
6ab0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 L] or.** [SQLITE
6ac0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 _SYNC_FULL]. Th
6ad0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 e first choice i
6ae0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 s the normal fsy
6af0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nc()..** The sec
6b00: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 ond choice is a
6b10: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
6b20: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 ullsync. The [S
6b30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
6b40: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 NLY].** flag may
6b50: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 be ORed in to i
6b60: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c ndicate that onl
6b70: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 y the data of th
6b80: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f e file.** and no
6b90: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 t its inode need
6ba0: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a s to be synced..
6bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 **.** The intege
6bc0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 r values to xLoc
6bd0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
6be0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 ) are one of.**
6bf0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
6c00: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
6c10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6c20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
6c30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6c40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a OCK_RESERVED],.*
6c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6c60: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
6c70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6c80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
6c90: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c ..** </ul>.** xL
6ca0: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 ock() increases
6cb0: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 the lock. xUnloc
6cc0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 k() decreases th
6cd0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 e lock..** The x
6ce0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
6cf0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b k() method check
6d00: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 s whether any da
6d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
6d20: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 n,.** either in
6d30: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 this process or
6d40: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 in some other pr
6d50: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e ocess, is holdin
6d60: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a g a RESERVED,.**
6d70: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 PENDING, or EXC
6d80: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 LUSIVE lock on t
6d90: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 he file. It ret
6da0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 urns true.** if
6db0: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 such a lock exis
6dc0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 ts and false oth
6dd0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erwise..**.** Th
6de0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 e xFileControl()
6df0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e method is a gen
6e00: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 eric interface t
6e10: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f hat allows custo
6e20: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 m.** VFS impleme
6e30: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 ntations to dire
6e40: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 ctly control an
6e50: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 open file using
6e60: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
6e70: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
6e80: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
6e90: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 second "op" argu
6ea0: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e ment is an.** in
6eb0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 teger opcode. T
6ec0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
6ed0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 t is a generic p
6ee0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 ointer intended
6ef0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 to.** point to a
6f00: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
6f10: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 may contain argu
6f20: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 ments or space i
6f30: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 n which to.** wr
6f40: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ite return value
6f50: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 s. Potential us
6f60: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 es for xFileCont
6f70: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a rol() might be.*
6f80: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 * functions to e
6f90: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c nable blocking l
6fa0: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 ocks with timeou
6fb0: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ts, to change th
6fc0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 e.** locking str
6fd0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 ategy (for examp
6fe0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 le to use dot-fi
6ff0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e le locks), to in
7000: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 quire.** about t
7010: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c he status of a l
7020: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b ock, or to break
7030: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 stale locks. T
7040: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 he SQLite.** cor
7050: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f e reserves all o
7060: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e pcodes less than
7070: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 100 for its own
7080: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 use..** A [SQLI
7090: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
70a0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 TE | list of opc
70b0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 odes] less than
70c0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 100 is available
70d0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
70e0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 s that define a
70f0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 custom xFileCont
7100: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c rol method shoul
7110: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a d use opcodes.**
7120: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 greater than 10
7130: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 0 to avoid confl
7140: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 icts. VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
7160: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
7170: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f ITE_NOTFOUND] fo
7180: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f r file control o
7190: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 pcodes that they
71a0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 do not.** recog
71b0: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nize..**.** The
71c0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 xSectorSize() me
71d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 thod returns the
71e0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 sector size of
71f0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 the.** device th
7200: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 at underlies the
7210: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 file. The sect
7220: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a or size is the.*
7230: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 * minimum write
7240: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 that can be perf
7250: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 ormed without di
7260: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 sturbing.** othe
7270: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 r bytes in the f
7280: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 ile. The xDevic
7290: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
72a0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
72b0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f urns a bit vecto
72c0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 r describing beh
72d0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a aviors of the.**
72e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 underlying devi
72f0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ce:.**.** <ul>.*
7300: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
7310: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 OCAP_ATOMIC].**
7320: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7330: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a AP_ATOMIC512].**
7340: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7350: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a CAP_ATOMIC1K].**
7360: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7370: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a CAP_ATOMIC2K].**
7380: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7390: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a CAP_ATOMIC4K].**
73a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
73b0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a CAP_ATOMIC8K].**
73c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
73d0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a CAP_ATOMIC16K].*
73e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
73f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a OCAP_ATOMIC32K].
7400: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d IOCAP_ATOMIC64K]
7420: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7430: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
7440: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ND].** <li> [SQL
7450: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
7460: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a TIAL].** </ul>.*
7470: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
7480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
7490: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
74a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
74b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
74c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
74d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
74e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
74f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
7500: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
7510: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
7520: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
7530: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
7540: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
7550: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
7560: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
7570: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
7580: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
7590: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
75a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
75b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
75c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
75d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
75e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
75f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
7600: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
7610: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
7620: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
7630: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7640: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
7650: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
7660: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
7670: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
7680: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
7690: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
76a0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
76b0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
76c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
76d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
76e0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
76f0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
7700: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
7710: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
7720: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
7730: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
7740: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
7750: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
7760: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
7770: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
7780: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
7790: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
77a0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
77b0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
77c0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
77d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
77e0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
77f0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
7800: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
7810: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
7820: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
7830: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
7840: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
7850: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
7860: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
7870: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
7880: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
7890: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
78a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
78b0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
78c0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
78d0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
78e0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
78f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
7900: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
7910: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
7920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7930: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
7940: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
7950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
7960: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
7970: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
7980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7990: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
79a0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
79b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
79c0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
79d0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
79e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
79f0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
7a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
7a10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
7a20: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
7a30: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
7a40: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
7a50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
7a60: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
7a70: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
7a80: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
7a90: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
7aa0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
7ab0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
7ac0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
7ad0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
7ae0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
7af0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
7b00: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
7b10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7b20: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
7b30: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
7b40: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
7b50: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
7b60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
7b70: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
7b90: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
7ba0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
7bb0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
7bc0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 2 */. /* Additi
7bd0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
7be0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
7bf0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
7c00: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
7c10: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
7c20: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
7c30: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e s.**.** These in
7c40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
7c50: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
7c60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
7c70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
7c80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
7c90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
7ca0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
7cb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
7cc0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
7cd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
7ce0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
7cf0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
7d00: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
7d10: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
7d20: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
7d30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
7d40: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
7d50: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
7d60: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
7d70: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
7d80: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
7d90: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
7da0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
7db0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
7dc0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
7dd0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
7de0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
7df0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
7e00: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
7e10: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
7e20: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
7e30: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
7e40: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
7e50: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
7e60: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
7e70: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
7e80: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 defined..**.** T
7e90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
7ea0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f _SIZE_HINT] opco
7eb0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 de is used by SQ
7ec0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 Lite to give the
7ed0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 VFS.** layer a
7ee0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 hint of how larg
7ef0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
7f00: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f ile will grow to
7f10: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a be during the.*
7f20: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 * current transa
7f30: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e ction. This hin
7f40: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 t is not guarant
7f50: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 eed to be accura
7f60: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 te but it.** is
7f70: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 often close. Th
7f80: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 e underlying VFS
7f90: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f might choose to
7fa0: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 preallocate dat
7fb0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 abase.** file sp
7fc0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 ace based on thi
7fd0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 s hint in order
7fe0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 to help writes t
7ff0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
8000: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 * file run faste
8010: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 r..**.** The [SQ
8020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
8030: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 _SIZE] opcode is
8040: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 used to request
8050: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a that the VFS.**
8060: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 extends and tru
8070: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 ncates the datab
8080: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e ase file in chun
8090: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 ks of a size spe
80a0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
80b0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 user. The fourt
80c0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 h argument to [s
80d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
80e0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a rol()] should .*
80f0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e * point to an in
8100: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 teger (type int)
8110: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
8120: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 new chunk-size t
8130: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 o use.** for the
8140: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 nominated datab
8150: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 ase. Allocating
8160: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 database file sp
8170: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 ace in large.**
8180: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 chunks (say 1MB
8190: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 at a time), may
81a0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 reduce file-syst
81b0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e em fragmentation
81c0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 and.** improve
81d0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 performance on s
81e0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a ome systems..**.
81f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8200: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
8210: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 R] opcode is use
8220: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f d to obtain a po
8230: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
8240: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
8250: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
8260: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
8270: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ar database.** c
8280: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 onnection. See
8290: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
82a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 e_control()] doc
82b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a umentation for.*
82c0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * additional inf
82d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
82e0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^(The [SQLITE_FC
82f0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
8300: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 ] opcode is gene
8310: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 rated internally
8320: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e by.** SQLite an
8330: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 d sent to all VF
8340: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 Ses in place of
8350: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 a call to the xS
8360: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 ync method.** wh
8370: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
8380: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b connection has [
8390: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
83a0: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 us] set to OFF.)
83b0: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 ^.** Some specia
83c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 lized VFSes need
83d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 this signal in
83e0: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 order to operate
83f0: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 correctly.** wh
8400: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 en [PRAGMA synch
8410: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 ronous | PRAGMA
8420: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d synchronous=OFF]
8430: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 is set, but mos
8440: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e t .** VFSes do n
8450: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 ot need this sig
8460: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 nal and should s
8470: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 ilently ignore t
8480: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 his opcode..** A
8490: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
84a0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c ld not call [sql
84b0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
84c0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a l()] with this.*
84d0: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e * opcode as doin
84e0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 g so may disrupt
84f0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f the operation o
8500: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 f the specialize
8510: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 d VFSes.** that
8520: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 do require it.
8530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
8540: 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f 4e 4c TE_FCNTL_READONL
8550: 59 5f 53 48 4d 5d 20 6d 61 79 20 62 65 20 67 65 Y_SHM] may be ge
8560: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
8570: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 69 66 0a ly by SQLite if.
8580: 2a 2a 20 74 68 65 20 22 72 65 61 64 6f 6e 6c 79 ** the "readonly
8590: 5f 73 68 6d 3d 31 22 20 55 52 49 20 6f 70 74 69 _shm=1" URI opti
85a0: 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 on is specified
85b0: 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
85c0: 65 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 e is opened..**
85d0: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d The fourth argum
85e0: 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20 74 68 ent passed to th
85f0: 65 20 56 46 53 20 78 46 69 6c 65 43 6f 6e 74 72 e VFS xFileContr
8600: 6f 6c 20 6d 65 74 68 6f 64 73 20 69 73 20 61 20 ol methods is a
8610: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 pointer.** to a
8620: 76 61 72 69 61 62 6c 65 20 6f 66 20 74 79 70 65 variable of type
8630: 20 22 69 6e 74 22 20 63 6f 6e 74 61 69 6e 69 6e "int" containin
8640: 67 20 74 68 65 20 76 61 6c 75 65 20 31 20 6f 72 g the value 1 or
8650: 20 30 2e 20 49 66 20 74 68 65 20 76 61 72 69 61 0. If the varia
8660: 62 6c 65 0a 2a 2a 20 63 6f 6e 74 61 69 6e 73 20 ble.** contains
8670: 74 68 65 20 76 61 6c 75 65 20 31 2c 20 74 68 65 the value 1, the
8680: 6e 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73 n this indicates
8690: 20 74 6f 20 74 68 65 20 56 46 53 20 74 68 61 74 to the VFS that
86a0: 20 61 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 20 a read-only.**
86b0: 6d 61 70 70 69 6e 67 20 6f 66 20 74 68 65 20 73 mapping of the s
86c0: 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 72 65 67 hared-memory reg
86d0: 69 6f 6e 20 69 73 20 61 63 63 65 70 74 61 62 6c ion is acceptabl
86e0: 65 2e 20 49 66 20 69 74 20 69 73 20 73 65 74 20 e. If it is set
86f0: 74 6f 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 to 0, then.** th
8700: 69 73 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 is indicates tha
8710: 74 20 61 20 72 65 61 64 2d 77 72 69 74 65 20 6d t a read-write m
8720: 61 70 70 69 6e 67 20 69 73 20 72 65 71 75 69 72 apping is requir
8730: 65 64 20 28 61 73 20 6e 6f 72 6d 61 6c 29 2e 20 ed (as normal).
8740: 49 66 0a 2a 2a 20 61 20 72 65 61 64 2d 6f 6e 6c If.** a read-onl
8750: 79 20 6d 61 70 70 69 6e 67 20 69 73 20 72 65 74 y mapping is ret
8760: 75 72 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 urned, then the
8770: 56 46 53 20 6d 61 79 20 61 6c 73 6f 20 72 65 74 VFS may also ret
8780: 75 72 6e 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a urn read-only.**
8790: 20 6d 61 70 70 69 6e 67 73 20 66 6f 72 20 61 6e mappings for an
87a0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 71 y subsequent req
87b0: 75 65 73 74 73 20 76 69 61 20 74 68 65 20 73 61 uests via the sa
87c0: 6d 65 20 66 69 6c 65 2d 64 65 73 63 72 69 70 74 me file-descript
87d0: 6f 72 20 2d 0a 2a 2a 20 72 65 67 61 72 64 6c 65 or -.** regardle
87e0: 73 73 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20 ss of the value
87f0: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
8800: 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a nfigured using.*
8810: 2a 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 * SQLITE_FCNTL_R
8820: 45 41 44 4f 4e 4c 59 5f 53 48 4d 2e 0a 2a 2a 0a EADONLY_SHM..**.
8830: 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ** In practice,
8840: 69 66 20 22 72 65 61 64 6f 6e 6c 79 5f 73 68 6d if "readonly_shm
8850: 3d 31 22 20 69 73 20 73 70 65 63 69 66 69 65 64 =1" is specified
8860: 20 61 6e 64 20 74 68 65 20 66 69 72 73 74 20 61 and the first a
8870: 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 6d 61 70 ttempt to.** map
8880: 20 61 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 a shared-memory
8890: 20 72 65 67 69 6f 6e 20 66 61 69 6c 73 2c 20 74 region fails, t
88a0: 68 65 6e 20 74 68 69 73 20 66 69 6c 65 2d 63 6f hen this file-co
88b0: 6e 74 72 6f 6c 20 69 73 20 69 6e 76 6f 6b 65 64 ntrol is invoked
88c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 61 72 67 with.** the arg
88d0: 75 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 20 73 ument variable s
88e0: 65 74 20 74 6f 20 31 20 61 6e 64 20 61 20 73 65 et to 1 and a se
88f0: 63 6f 6e 64 20 61 74 74 65 6d 70 74 20 74 6f 20 cond attempt to
8900: 6d 61 70 20 74 68 65 20 73 68 61 72 65 64 2d 6d map the shared-m
8910: 65 6d 6f 72 79 0a 2a 2a 20 72 65 67 69 6f 6e 20 emory.** region
8920: 69 73 20 6d 61 64 65 2e 20 49 66 20 74 68 69 73 is made. If this
8930: 20 6d 61 70 70 69 6e 67 20 73 75 63 63 65 65 64 mapping succeed
8940: 73 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 6e s, then the conn
8950: 65 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 ection continues
8960: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 72 65 61 .** with the rea
8970: 64 2d 6f 6e 6c 79 20 6d 61 70 70 69 6e 67 2e 20 d-only mapping.
8980: 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 69 74 Otherwise, if it
8990: 20 66 61 69 6c 73 2c 20 53 51 4c 49 54 45 5f 43 fails, SQLITE_C
89a0: 41 4e 54 4f 50 45 4e 20 69 73 0a 2a 2a 20 72 65 ANTOPEN is.** re
89b0: 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 turned to the ca
89c0: 6c 6c 65 72 2e 20 57 68 65 74 68 65 72 20 6f 72 ller. Whether or
89d0: 20 6e 6f 74 20 74 68 65 20 73 65 63 6f 6e 64 20 not the second
89e0: 28 72 65 61 64 2d 6f 6e 6c 79 29 20 6d 61 70 70 (read-only) mapp
89f0: 69 6e 67 0a 2a 2a 20 61 74 74 65 6d 70 74 20 73 ing.** attempt s
8a00: 75 63 63 65 65 64 73 2c 20 74 68 65 20 66 69 6c ucceeds, the fil
8a10: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 69 6e 76 e-control is inv
8a20: 6f 6b 65 64 20 61 67 61 69 6e 20 77 69 74 68 20 oked again with
8a30: 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 the argument.**
8a40: 76 61 72 69 61 62 6c 65 20 73 65 74 20 74 6f 20 variable set to
8a50: 30 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 0..*/.#define SQ
8a60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
8a70: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 TATE 1.#d
8a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 efine SQLITE_GET
8a90: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
8aa0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
8ab0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
8ac0: 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 XYFILE 3.#d
8ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
8ae0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
8af0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
8b00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
8b10: 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 HINT 5.#d
8b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
8b30: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 TL_CHUNK_SIZE
8b40: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
8b50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
8b60: 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 POINTER 7.#d
8b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
8b80: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 TL_SYNC_OMITTED
8b90: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
8ba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f LITE_FCNTL_READO
8bb0: 4e 4c 59 5f 53 48 4d 20 20 20 20 20 39 0a 0a 0a NLY_SHM 9...
8bc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8bd0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a Mutex Handle.**.
8be0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
8bf0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
8c00: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
8c10: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
8c20: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
8c30: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
8c40: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
8c50: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
8c60: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
8c70: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
8c80: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
8c90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
8ca0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
8cb0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
8cc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
8cd0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
8ce0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
8cf0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
8d00: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
8d10: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
8d20: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
8d30: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
8d40: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
8d50: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
8d60: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 ce Object.** KEY
8d70: 57 4f 52 44 53 3a 20 56 46 53 20 56 46 53 65 73 WORDS: VFS VFSes
8d80: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
8d90: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ce of the sqlite
8da0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 3_vfs object def
8db0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
8dc0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 ce between.** th
8dd0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e e SQLite core an
8de0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
8df0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
8e00: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a m. The "vfs".**
8e10: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 in the name of
8e20: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 the object stand
8e30: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 s for "virtual f
8e40: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a ile system"..**.
8e50: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
8e60: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
8e70: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
8e80: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
8e90: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
8ea0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
8eb0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
8ec0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
8ed0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
8ee0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
8ef0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
8f00: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
8f10: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
8f20: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
8f30: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
8f40: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
8f50: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
8f60: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
8f70: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
8f80: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
8f90: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
8fa0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
8fb0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
8fc0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
8fd0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
8fe0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
8ff0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
9000: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
9010: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
9020: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
9030: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
9040: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
9050: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
9060: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
9070: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
9080: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
9090: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
90a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
90b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
90c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
90d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
90e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
90f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
9100: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
9110: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
9120: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
9130: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
9140: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
9150: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
9160: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
9170: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
9180: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
9190: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
91a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
91b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
91c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
91d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
91e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
91f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
9200: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
9210: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
9220: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
9230: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
9240: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
9250: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
9260: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
9270: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
9280: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
9290: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
92a0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
92b0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
92c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
92d0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
92e0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
92f0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
9300: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
9310: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
9320: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
9330: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
9340: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
9350: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
9360: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
9370: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 ^SQLite guarante
9380: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c es that the zFil
9390: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
93a0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 to xOpen.** is e
93b0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ither a NULL poi
93c0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f nter or string o
93d0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
93e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 xFullPathname()
93f0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c with an optional
9400: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a suffix added..*
9410: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 * ^If a suffix i
9420: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a s added to the z
9430: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
9440: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 er, it will.** c
9450: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 onsist of a sing
9460: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 le "-" character
9470: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 followed by no
9480: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 more than.** 10
9490: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 alphanumeric and
94a0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 /or "-" characte
94b0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 rs..** ^SQLite f
94c0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 urther guarantee
94d0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 s that.** the st
94e0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c ring will be val
94f0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 id and unchanged
9500: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 until xClose()
9510: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 is.** called. Be
9520: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 cause of the pre
9530: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a vious sentence,.
9540: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
9550: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 file] can safely
9560: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 store a pointer
9570: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e to the.** filen
9580: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 ame if it needs
9590: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 to remember the
95a0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d filename for som
95b0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 e reason..** If
95c0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
95d0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
95e0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
95f0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a er then xOpen.**
9600: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 must invent its
9610: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e own temporary n
9620: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 ame for the file
9630: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 . ^Whenever the
9640: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 .** xFilename p
9650: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c arameter is NULL
9660: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 it will also be
9670: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
9680: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 he.** flags para
9690: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 meter will inclu
96a0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
96b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a DELETEONCLOSE]..
96c0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
96d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
96e0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c n() includes all
96f0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 bits set in.**
9700: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
9710: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f nt to [sqlite3_o
9720: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 pen_v2()]. Or i
9730: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
9740: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
9750: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 3_open16()] is u
9760: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 sed, then flags
9770: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 includes at leas
9780: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 t.** [SQLITE_OPE
9790: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
97a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
97b0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 TE]. .** If xOpe
97c0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 n() opens a file
97d0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 read-only then
97e0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 it sets *pOutFla
97f0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 gs to.** include
9800: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
9810: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 ADONLY]. Other
9820: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 bits in *pOutFla
9830: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a gs may be set..*
9840: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 *.** ^(SQLite wi
9850: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
9860: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
9870: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
9880: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
9890: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
98a0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
98b0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ned:.**.** <ul>.
98c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
98d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
98e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
98f0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
9900: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
9910: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
9920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
9930: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
9940: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
9950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
9960: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
9970: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
9980: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
9990: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
99a0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
99b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
99c0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 TE_OPEN_WAL].**
99d0: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
99e0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 e file I/O imple
99f0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 mentation can us
9a00: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 e the object typ
9a10: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 e flags to.** ch
9a20: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 ange the way it
9a30: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 deals with files
9a40: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
9a50: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a an application.*
9a60: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 * that does not
9a70: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 care about crash
9a80: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c recovery or rol
9a90: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 lback might make
9aa0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 .** the open of
9ab0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 a journal file a
9ac0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 no-op. Writes
9ad0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 to this journal
9ae0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 would.** also be
9af0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 no-ops, and any
9b00: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 attempt to read
9b10: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 the journal wou
9b20: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ld return.** SQL
9b30: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 ITE_IOERR. Or t
9b40: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
9b50: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
9b60: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 e that a databas
9b70: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 e.** file will b
9b80: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 e doing page-ali
9b90: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 gned sector read
9ba0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 s and writes in
9bb0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 a random.** orde
9bc0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 r and set up its
9bd0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 I/O subsystem a
9be0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a ccordingly..**.*
9bf0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
9c00: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
9c10: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
9c20: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 gs to the xOpen
9c30: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
9c40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
9c50: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
9c60: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b CLOSE].** <li> [
9c70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
9c80: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a USIVE].** </ul>.
9c90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
9ca0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
9cb0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 LOSE] flag means
9cc0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
9cd0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 be.** deleted w
9ce0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 hen it is closed
9cf0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
9d00: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
9d10: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 SE].** will be s
9d20: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 et for TEMP data
9d30: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 bases and their
9d40: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 journals, transi
9d50: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 ent.** databases
9d60: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c , and subjournal
9d70: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 s..**.** ^The [S
9d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
9d90: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c SIVE] flag is al
9da0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e ways used in con
9db0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 junction.** with
9dc0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
9dd0: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 N_CREATE] flag,
9de0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 which are both d
9df0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f irectly.** analo
9e00: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 gous to the O_EX
9e10: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 CL and O_CREAT f
9e20: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 lags of the POSI
9e30: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e X open().** API.
9e40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 The SQLITE_OPE
9e50: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 N_EXCLUSIVE flag
9e60: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 , when paired wi
9e70: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 th the .** SQLIT
9e80: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 E_OPEN_CREATE, i
9e90: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 s used to indica
9ea0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f te that file sho
9eb0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 uld always.** be
9ec0: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 created, and th
9ed0: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f at it is an erro
9ee0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 r if it already
9ef0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 exists..** It is
9f00: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 <i>not</i> used
9f10: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 to indicate the
9f20: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 file should be
9f30: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 opened .** for e
9f40: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
9f50: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 .**.** ^At least
9f60: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 szOsFile bytes
9f70: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c of memory are al
9f80: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 located by SQLit
9f90: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 e.** to hold the
9fa0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d [sqlite3_file]
9fb0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 structure passe
9fc0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a d as the third.*
9fd0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f * argument to xO
9fe0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 pen. The xOpen
9ff0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 method does not
a000: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 have to.** alloc
a010: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 ate the structur
a020: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 e; it should jus
a030: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e t fill it in. N
a040: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ote that.** the
a050: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 xOpen method mus
a060: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 t set the sqlite
a070: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
a080: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 to either.** a v
a090: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f alid [sqlite3_io
a0a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
a0b0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f or to NULL. xO
a0c0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 pen must do.** t
a0d0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 his even if the
a0e0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c open fails. SQL
a0f0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 ite expects that
a100: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
a110: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c e.pMethods.** el
a120: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 ement will be va
a130: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 lid after xOpen
a140: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 returns regardle
a150: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 ss of the succes
a160: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 s.** or failure
a170: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c of the xOpen cal
a180: 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c l..**.** ^The fl
a190: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
a1a0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 xAccess() may be
a1b0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
a1c0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 EXISTS].** to te
a1d0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 st for the exist
a1e0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 ence of a file,
a1f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
a200: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a S_READWRITE] to.
a210: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 ** test whether
a220: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 a file is readab
a230: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c le and writable,
a240: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 or [SQLITE_ACCE
a250: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 SS_READ].** to t
a260: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
a270: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 le is at least r
a280: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 eadable. The f
a290: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 ile can be a.**
a2a0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
a2b0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^SQLite will al
a2c0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 ways allocate at
a2d0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d least mxPathnam
a2e0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 e+1 bytes for th
a2f0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 e.** output buff
a300: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 er xFullPathname
a310: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a . The exact siz
a320: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 e of the output
a330: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 buffer.** is als
a340: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 o passed as a pa
a350: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 rameter to both
a360: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 methods. If the
a370: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
a380: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 * is not large e
a390: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 nough, [SQLITE_C
a3a0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 ANTOPEN] should
a3b0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e be returned. Sin
a3c0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 ce this is.** ha
a3d0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c ndled as a fatal
a3e0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 error by SQLite
a3f0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 , vfs implementa
a400: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 tions should end
a410: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 eavor.** to prev
a420: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 ent this by sett
a430: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 ing mxPathname t
a440: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 o a sufficiently
a450: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a large value..**
a460: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
a470: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c ess(), xSleep(),
a480: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c xCurrentTime(),
a490: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d and xCurrentTim
a4a0: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 eInt64().** inte
a4b0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 rfaces are not s
a4c0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
a4d0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
a4e0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
a4f0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
a500: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
a510: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
a520: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
a530: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
a540: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
a550: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
a560: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
a570: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
a580: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
a590: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
a5a0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
a5b0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
a5c0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
a5d0: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 ed..** The xSlee
a5e0: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 p() method cause
a5f0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 s the calling th
a600: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f read to sleep fo
a610: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 r at.** least th
a620: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 e number of micr
a630: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 oseconds given.
a640: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
a650: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
a660: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
a670: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
a680: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
a690: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 and time as.** a
a6a0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
a6b0: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 value..** ^The x
a6c0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
a6d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
a6e0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 s, as an integer
a6f0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 , the Julian.**
a700: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 Day Number multi
a710: 70 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 pled by 86400000
a720: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 (the number of
a730: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 milliseconds in
a740: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 .** a 24-hour da
a750: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 y). .** ^SQLite
a760: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 will use the xC
a770: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
a780: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 ) method to get
a790: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 the current.** d
a7a0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 ate and time if
a7b0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 that method is a
a7c0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 vailable (if iVe
a7d0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a rsion is 2 or .*
a7e0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 * greater and th
a7f0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 e function point
a800: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 er is not NULL)
a810: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 and will fall ba
a820: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e ck.** to xCurren
a830: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 tTime() if xCurr
a840: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 entTimeInt64() i
a850: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
a860: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 *.** ^The xSetSy
a870: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 stemCall(), xGet
a880: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e SystemCall(), an
a890: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c d xNestSystemCal
a8a0: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a l() interfaces.*
a8b0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 * are not used b
a8c0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 y the SQLite cor
a8d0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e e. These option
a8e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
a8f0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 e provided.** by
a900: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 some VFSes to f
a910: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e acilitate testin
a920: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 g of the VFS cod
a930: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 e. By overriding
a940: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c .** system call
a950: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 s with functions
a960: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 under its contr
a970: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 ol, a test progr
a980: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 am can.** simula
a990: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 te faults and er
a9a0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 ror conditions t
a9b0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 hat would otherw
a9c0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 ise be difficult
a9d0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c .** or impossibl
a9e0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 e to induce. Th
a9f0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 e set of system
aa00: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 calls that can b
aa10: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 e overridden.**
aa20: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 varies from one
aa30: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 VFS to another,
aa40: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 and from one ver
aa50: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 sion of the same
aa60: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e VFS to the.** n
aa70: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
aa80: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 ns that use thes
aa90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 e interfaces mus
aaa0: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f t be prepared fo
aab0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 r any.** or all
aac0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 of these interfa
aad0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f ces to be NULL o
aae0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 r for their beha
aaf0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a vior to change.*
ab00: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 * from one relea
ab10: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 se to the next.
ab20: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 Applications mu
ab30: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 st not attempt t
ab40: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 o access.** any
ab50: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 of these methods
ab60: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e if the iVersion
ab70: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c of the VFS is l
ab80: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 ess than 3..*/.t
ab90: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
aba0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
abb0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 3_vfs;.typedef v
abc0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 oid (*sqlite3_sy
abd0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 scall_ptr)(void)
abe0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
abf0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 _vfs {. int iVe
ac00: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 rsion;
ac10: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 /* Structure v
ac20: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 ersion number (c
ac30: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 urrently 3) */.
ac40: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
ac50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
ac60: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
ac70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
ac80: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
ac90: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
aca0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
acb0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
acc0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
acd0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
ace0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
acf0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
ad00: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
ad10: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
ad20: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
ad30: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
ad40: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
ad50: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
ad60: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
ad70: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
ad80: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
ad90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
ada0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
adb0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
adc0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
add0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
ade0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
adf0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
ae00: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ae10: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
ae20: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
ae30: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
ae40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ae50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
ae60: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
ae70: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
ae80: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f thname)(sqlite3_
ae90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
aea0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 *zName, int nOu
aeb0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a t, char *zOut);.
aec0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 void *(*xDlOpe
aed0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
aee0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
aef0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 lename);. void
af00: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 (*xDlError)(sqli
af10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
af20: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d yte, char *zErrM
af30: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a sg);. void (*(*
af40: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
af50: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
af60: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
af70: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 )(void);. void
af80: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 (*xDlClose)(sqli
af90: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 te3_vfs*, void*)
afa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f ;. int (*xRando
afb0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 mness)(sqlite3_v
afc0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
afd0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 char *zOut);. i
afe0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c nt (*xSleep)(sql
aff0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
b000: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 icroseconds);.
b010: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
b020: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
b030: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e , double*);. in
b040: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f t (*xGetLastErro
b050: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
b060: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 int, char *);.
b070: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
b080: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
b090: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
b0a0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
b0b0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 ject. ** defini
b0c0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 tion. Those tha
b0d0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 t follow are add
b0e0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 ed in version 2
b0f0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 or later. */.
b100: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
b110: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 meInt64)(sqlite3
b120: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 _vfs*, sqlite3_i
b130: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a nt64*);. /*. *
b140: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
b150: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
b160: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 ons 1 and 2 of t
b170: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
b180: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 ject.. ** Those
b190: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 below are for v
b1a0: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 ersion 3 and gre
b1b0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 ater.. */. int
b1c0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c (*xSetSystemCal
b1d0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
b1e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
b1f0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 me, sqlite3_sysc
b200: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 all_ptr);. sqli
b210: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 te3_syscall_ptr
b220: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xGetSystemCall
b230: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
b240: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
b250: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 e);. const char
b260: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 *(*xNextSystemC
b270: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
b280: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
b290: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a Name);. /*. **
b2a0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
b2b0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
b2c0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f ns 1 through 3 o
b2d0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
b2e0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 object.. ** Ne
b2f0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
b300: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
b310: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
b320: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
b330: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
b340: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
b350: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a is happens. . *
b360: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
b370: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
b380: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
b390: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
b3a0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
b3b0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 ants can be used
b3c0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 as the third pa
b3d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
b3e0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
b3f0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
b400: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 vfs] object. Th
b410: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 ey determine.**
b420: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 what kind of per
b430: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 missions the xAc
b440: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c cess method is l
b450: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 ooking for..** W
b460: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
b470: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
b480: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
b490: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 simply checks wh
b4a0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 ether the file e
b4b0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 xists..** With S
b4c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
b4d0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 DWRITE, the xAcc
b4e0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
b4f0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
b500: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 named directory
b510: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c is both readabl
b520: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a e and writable.*
b530: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 * (in other word
b540: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 s, if files can
b550: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 be added, remove
b560: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 d, and renamed w
b570: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 ithin.** the dir
b580: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 ectory)..** The
b590: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
b5a0: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 ADWRITE constant
b5b0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 is currently us
b5c0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a ed only by the.*
b5d0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 * [temp_store_di
b5e0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c rectory pragma],
b5f0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 though this cou
b600: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ld change in a f
b610: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
b620: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 of SQLite..** W
b630: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
b640: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 S_READ, the xAcc
b650: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
b660: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
b670: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
b680: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 e. The SQLITE_A
b690: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 CCESS_READ const
b6a0: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e ant is.** curren
b6b0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 tly unused, thou
b6c0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 gh it might be u
b6d0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 sed in a future
b6e0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
b6f0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
b700: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
b710: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
b720: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
b730: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f _READWRITE 1 /
b740: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 * Used by PRAGMA
b750: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 temp_store_dire
b760: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ctory */.#define
b770: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
b780: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 EAD 2 /*
b790: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a Unused */../*.**
b7a0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
b7b0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 for the xShmLoc
b7c0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a k VFS method.**.
b7d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
b7e0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
b7f0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f e the various lo
b800: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 cking operations
b810: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 .** allowed by t
b820: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
b830: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 od of [sqlite3_i
b840: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 o_methods]. The
b850: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 .** following ar
b860: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c e the only legal
b870: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 combinations of
b880: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a flags to the.**
b890: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
b8a0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
b8b0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
b8c0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 _LOCK | SQLITE_S
b8d0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 HM_SHARED.** <li
b8e0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
b8f0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
b900: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 EXCLUSIVE.** <li
b910: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e > SQLITE_SHM_UN
b920: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
b930: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
b940: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
b950: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
b960: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f _EXCLUSIVE.** </
b970: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 ul>.**.** When u
b980: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 nlocking, the sa
b990: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 me SHARED or EXC
b9a0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 LUSIVE flag must
b9b0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a be supplied as.
b9c0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 ** was given no
b9d0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
b9e0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 g lock. .**.**
b9f0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 The xShmLock met
ba00: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 hod can transiti
ba10: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 on between unloc
ba20: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f ked and SHARED o
ba30: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c r.** between unl
ba40: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 ocked and EXCLUS
ba50: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 IVE. It cannot
ba60: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
ba70: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 en SHARED.** and
ba80: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 EXCLUSIVE..*/.#
ba90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
baa0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 M_UNLOCK 1
bab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bac0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 SHM_LOCK
bad0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
bae0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 E_SHM_SHARED
baf0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
bb00: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
bb10: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 E 8../*.** CA
bb20: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 PI3REF: Maximum
bb30: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a xShmLock index.*
bb40: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
bb50: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c k method on [sql
bb60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
bb70: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a may use values.
bb80: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ** between 0 and
bb90: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e this upper boun
bba0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 d as its "offset
bbb0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 " argument..** T
bbc0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 he SQLite core w
bbd0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 ill never attemp
bbe0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 t to acquire or
bbf0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 release a.** loc
bc00: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 k outside of thi
bc10: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 s range.*/.#defi
bc20: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c ne SQLITE_SHM_NL
bc30: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f OCK 8.../
bc40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
bc50: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
bc60: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
bc70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
bc80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
bc90: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
bca0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
bcb0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
bcc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
bcd0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
bce0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
bcf0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
bd00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
bd10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
bd20: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
bd30: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
bd40: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
bd50: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
bd60: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
bd70: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
bd80: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
bd90: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
bda0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
bdb0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
bdc0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
bdd0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
bde0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
bdf0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
be00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
be10: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
be20: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
be30: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
be40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
be50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
be60: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
be70: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
be80: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
be90: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
bea0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
beb0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
bec0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
bed0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
bee0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
bef0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
bf00: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
bf10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
bf20: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
bf30: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
bf40: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
bf50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
bf60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
bf70: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
bf80: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
bf90: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
bfa0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
bfb0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
bfc0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
bfd0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
bfe0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
bff0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
c000: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
c010: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
c020: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
c030: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
c040: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
c050: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
c060: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
c070: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
c080: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
c090: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
c0a0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
c0b0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
c0c0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
c0d0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
c0e0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
c0f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
c100: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
c110: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
c120: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
c130: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
c140: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c150: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
c160: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
c170: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
c180: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
c190: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
c1a0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
c1b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
c1c0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
c1d0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
c1e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
c1f0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
c200: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
c210: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
c220: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
c230: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
c240: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
c250: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
c260: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
c270: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
c280: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
c290: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
c2a0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
c2b0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
c2c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
c2d0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
c2e0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
c2f0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
c300: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
c310: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
c320: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
c330: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
c340: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
c350: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
c360: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
c370: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
c380: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
c390: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
c3a0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
c3b0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
c3c0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
c3d0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
c3e0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
c3f0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
c400: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
c410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
c420: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
c430: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
c440: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
c450: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
c460: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
c470: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
c480: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
c490: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
c4a0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
c4b0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
c4c0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
c4d0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
c4e0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
c4f0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
c500: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
c510: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
c520: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
c530: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
c540: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
c550: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
c560: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
c570: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
c580: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
c590: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
c5a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
c5b0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
c5c0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
c5d0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
c5e0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
c5f0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
c600: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
c610: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
c620: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
c630: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
c640: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
c650: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
c660: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
c670: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
c680: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
c690: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
c6a0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
c6b0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
c6c0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
c6d0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
c6e0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
c6f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
c700: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
c710: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
c720: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
c730: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
c740: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
c750: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
c760: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
c770: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
c780: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
c790: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
c7a0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
c7b0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
c7c0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
c7d0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
c7e0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
c7f0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
c800: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
c810: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
c820: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
c830: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
c840: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
c850: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
c860: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
c870: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
c880: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
c890: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
c8a0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
c8b0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
c8c0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
c8d0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
c8e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
c8f0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
c900: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
c910: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
c920: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
c930: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
c940: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
c950: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
c960: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
c970: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
c980: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
c990: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
c9a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
c9b0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
c9c0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
c9d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
c9e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
c9f0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
ca00: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
ca10: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
ca20: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
ca30: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
ca40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ca50: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
ca60: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
ca70: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
ca80: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
ca90: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
caa0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
cab0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
cac0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
cad0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
cae0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
caf0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
cb00: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
cb10: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
cb20: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
cb30: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
cb40: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
cb50: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
cb60: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
cb70: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
cb80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
cb90: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
cba0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
cbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
cbc0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
cbd0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
cbe0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
cbf0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
cc00: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
cc10: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
cc20: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
cc30: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
cc40: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
cc50: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
cc60: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
cc70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
cc80: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
cc90: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
cca0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
ccb0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
ccc0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
ccd0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
cce0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
ccf0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
cd00: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ary.**.** The sq
cd10: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
cd20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
cd30: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
cd40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
cd50: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
cd60: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
cd70: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
cd80: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
cd90: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
cda0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
cdb0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
cdc0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
cdd0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
cde0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
cdf0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
ce00: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
ce10: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
ce20: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
ce30: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
ce40: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
ce50: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
ce60: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
ce70: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
ce80: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
ce90: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
cea0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
ceb0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
cec0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
ced0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
cee0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
cef0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
cf00: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
cf10: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
cf20: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
cf30: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
cf40: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
cf50: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
cf60: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
cf70: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
cf80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
cf90: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
cfa0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
cfb0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
cfc0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
cfd0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
cfe0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
cff0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
d000: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
d010: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
d020: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
d030: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
d040: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
d050: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
d060: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
d070: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
d080: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
d090: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
d0a0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
d0b0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
d0c0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
d0d0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
d0e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
d0f0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
d100: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
d110: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c G_SINGLETHREAD |
d120: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
d130: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
d140: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
d150: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
d160: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
d170: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
d180: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
d190: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
d1a0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f n the [SQLITE_CO
d1b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
d1c0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f D | configuratio
d1d0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
d1e0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
d1f0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
d200: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
d210: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
d220: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
d230: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
d240: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
d250: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
d260: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
d270: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
d280: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
d290: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
d2a0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
d2b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
d2c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e .int sqlite3_con
d2d0: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
d2e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
d2f0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
d300: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
d310: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
d320: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
d330: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
d340: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
d350: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
d360: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
d370: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
d380: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
d390: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
d3a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
d3b0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
d3c0: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
d3d0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
d3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d3f0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
d400: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
d410: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nt)..**.** The s
d420: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
d430: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
d440: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 fig(D,V,...) is
d450: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
d460: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
d470: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 DE | configurati
d480: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e on verb] - an in
d490: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 teger code .** t
d4a0: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
d4b0: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 at aspect of the
d4c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
d4d0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
d4e0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 configured..** S
d4f0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
d500: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 nts vary dependi
d510: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 ng on the config
d520: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a uration verb..**
d530: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 .** ^Calls to sq
d540: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
d550: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
d560: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 OK if and only i
d570: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 f.** the call is
d580: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 considered succ
d590: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 essful..*/.int s
d5a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d5b0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
d5c0: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
d5d0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
d5e0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
d5f0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ines.**.** An in
d600: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
d610: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
d620: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
d630: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e een SQLite.** an
d640: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f d low-level memo
d650: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
d660: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
d670: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 is object is use
d680: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c d in only one pl
d690: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ace in the SQLit
d6a0: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
d6b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
d6c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
d6d0: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 object is the a
d6e0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 rgument to.** [s
d6f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
d700: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 when the config
d710: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
d720: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e s.** [SQLITE_CON
d730: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b FIG_MALLOC] or [
d740: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
d750: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 TMALLOC]. .** B
d760: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e y creating an in
d770: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
d780: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 bject.** and pas
d790: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
d7a0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
d7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
d7c0: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f C]).** during co
d7d0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 nfiguration, an
d7e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 application can
d7f0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
d800: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
d810: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
d820: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 ystem for SQLite
d830: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 to use for all
d840: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 of its.** dynami
d850: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a c memory needs..
d860: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
d870: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 SQLite comes wit
d880: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 h several [built
d890: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
d8a0: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 ators].** that a
d8b0: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 re perfectly ade
d8c0: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 quate for the ov
d8d0: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 erwhelming major
d8e0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
d8f0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ons.** and that
d900: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f this object is o
d910: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 nly useful to a
d920: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 tiny minority of
d930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
d940: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 with specialize
d950: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
d960: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 ion requirements
d970: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 . This object i
d980: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 s.** also used d
d990: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 uring testing of
d9a0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
d9b0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 to specify an a
d9c0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
d9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
d9e0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 hat simulates me
d9f0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f mory out-of-memo
da00: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e ry conditions in
da10: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 .** order to ver
da20: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 ify that SQLite
da30: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 recovers gracefu
da40: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a lly from such.**
da50: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a conditions..**.
da60: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 ** The xMalloc a
da70: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 nd xFree methods
da80: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 must work like
da90: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 the.** malloc()
daa0: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 and free() funct
dab0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
dac0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
dad0: 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f ..** The xReallo
dae0: 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f c method must wo
daf0: 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 rk like realloc(
db00: 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 ) from the stand
db10: 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a ard C library.**
db20: 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 with the except
db30: 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 ion that if the
db40: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
db50: 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a to xRealloc is z
db60: 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 ero,.** xRealloc
db70: 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 must be a no-op
db80: 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 - it must not p
db90: 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 erform any alloc
dba0: 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c ation or.** deal
dbb0: 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 location. ^SQLi
dbc0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
dbd0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 at the second ar
dbe0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 gument to.** xRe
dbf0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 alloc is always
dc00: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 a value returned
dc10: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c by a prior call
dc20: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a to xRoundup..**
dc30: 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 And so in cases
dc40: 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 where xRoundup
dc50: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
dc60: 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 positive number
dc70: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 ,.** xRealloc ca
dc80: 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c n perform exactl
dc90: 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 y as the standar
dca0: 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f d library reallo
dcb0: 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c c() and.** still
dcc0: 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 be in complianc
dcd0: 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 e with this spec
dce0: 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ification..**.**
dcf0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 xSize should re
dd00: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 turn the allocat
dd10: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d ed size of a mem
dd20: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
dd30: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 * previously obt
dd40: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c ained from xMall
dd50: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 oc or xRealloc.
dd60: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 The allocated s
dd70: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ize.** is always
dd80: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 at least as big
dd90: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 as the requeste
dda0: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 d size but may b
ddb0: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 e larger..**.**
ddc0: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 The xRoundup met
ddd0: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 hod returns what
dde0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c would be the al
ddf0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a located size of.
de00: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ** a memory allo
de10: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 cation given a p
de20: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 articular reques
de30: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 ted size. Most
de40: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
de50: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 tors round up me
de60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
de70: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 at least to the
de80: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a next multiple.*
de90: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c * of 8. Some al
dea0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
deb0: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 p to a larger mu
dec0: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 ltiple or to a p
ded0: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 ower of 2..** Ev
dee0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ery memory alloc
def0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f ation request co
df00: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 ming in through
df10: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
df20: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
df30: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 3_realloc()] fir
df40: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 st calls xRoundu
df50: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 p. If xRoundup
df60: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 returns 0, .** t
df70: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 hat causes the c
df80: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d orresponding mem
df90: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
dfa0: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 o fail..**.** Th
dfb0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 e xInit method i
dfc0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d nitializes the m
dfd0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e emory allocator.
dfe0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a (For example,.
dff0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
e000: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
e010: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
e020: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
e030: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
e040: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
e050: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
e060: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
e070: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
e080: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
e090: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
e0a0: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
e0b0: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
e0c0: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
e0d0: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
e0e0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
e0f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
e100: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
e110: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 down..**.** SQLi
e120: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 te holds the [SQ
e130: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
e140: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 C_MASTER] mutex
e150: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
e160: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
e170: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
e180: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
e190: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
e1a0: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
e1b0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
e1c0: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
e1d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
e1e0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
e1f0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
e200: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
e210: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 r. For all othe
e220: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 r methods, SQLit
e230: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b e.** holds the [
e240: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
e250: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 TIC_MEM] mutex a
e260: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a s long as the.**
e270: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
e280: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 MEMSTATUS] confi
e290: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
e2a0: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 is turned on (wh
e2b0: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 ich.** it is by
e2c0: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 default) and so
e2d0: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 the methods are
e2e0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 automatically se
e2f0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 rialized..** How
e300: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 ever, if [SQLITE
e310: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
e320: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 S] is disabled,
e330: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a then the other.*
e340: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 * methods must b
e350: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 e threadsafe or
e360: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 else make their
e370: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 own arrangements
e380: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a for.** serializ
e390: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ation..**.** SQL
e3a0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 ite will never i
e3b0: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f nvoke xInit() mo
e3c0: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 re than once wit
e3d0: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e hout an interven
e3e0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 ing.** call to x
e3f0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 Shutdown()..*/.t
e400: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
e410: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
e420: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
e430: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
e440: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
e450: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
e460: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
e470: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
e480: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
e490: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
e4a0: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
e4b0: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
e4c0: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
e4d0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
e4e0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
e4f0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
e500: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
e510: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
e520: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
e530: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
e540: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
e550: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
e560: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
e570: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
e580: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
e590: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
e5a0: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
e5b0: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
e5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
e5d0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
e5e0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
e5f0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
e600: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
e610: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
e620: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
e630: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
e640: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
e650: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
e660: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
e670: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
e680: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
e690: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
e6a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
e6b0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
e6c0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
e6d0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
e6e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e6f0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
e700: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
e710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
e720: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
e730: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
e740: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
e750: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
e760: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
e770: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
e780: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
e790: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
e7a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
e7b0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
e7c0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
e7d0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
e7e0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
e7f0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
e800: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
e810: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
e820: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
e830: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
e840: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
e850: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
e860: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
e870: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
e880: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
e890: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
e8a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
e8b0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
e8c0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
e8d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
e8e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
e8f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
e900: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
e910: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
e920: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
e930: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
e940: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
e950: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
e960: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
e970: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
e980: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
e990: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
e9a0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
e9b0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
e9c0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
e9d0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
e9e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
e9f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
ea00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
ea10: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
ea20: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
ea30: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
ea40: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
ea50: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
ea60: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
ea70: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
ea80: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
ea90: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
eaa0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
eab0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
eac0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
ead0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
eae0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
eaf0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
eb00: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
eb10: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
eb20: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
eb30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
eb40: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a ULTITHREAD</dt>.
eb50: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
eb60: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
eb70: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
eb80: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
eba0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 ng mode] to Mult
ebb0: 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 i-thread. In ot
ebc0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 her words, it di
ebd0: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 sables.** mutexi
ebe0: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ng on [database
ebf0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
ec00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
ec10: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a ent] objects..**
ec20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
ec30: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
ec40: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 for serializing
ec50: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 access to.** [da
ec60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ec70: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
ec80: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 d statements].
ec90: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 But other mutexe
eca0: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 s.** are enabled
ecb0: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 so that SQLite
ecc0: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 will be safe to
ecd0: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 use in a multi-t
ece0: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 hreaded.** envir
ecf0: 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 onment as long a
ed00: 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 s no two threads
ed10: 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
ed20: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 the same.** [dat
ed30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ed40: 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 ] at the same ti
ed50: 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 me. ^If SQLite
ed60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
ed70: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
ed80: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
ed90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
eda0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
edb0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
edc0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
edd0: 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 to set the Mult
ede0: 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
edf0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
ee00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
ee10: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
ee20: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
ee30: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
ee40: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
ee50: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 IG_MULTITHREAD c
ee60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ee70: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
ee80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
ee90: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
eea0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
eeb0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
eec0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
eed0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
eee0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
eef0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
ef00: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
ef10: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
ef20: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
ef30: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
ef40: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
ef50: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
ef60: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
ef70: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
ef80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
ef90: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
efa0: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
efb0: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
efc0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
efd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
efe0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
eff0: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
f000: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
f010: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
f020: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
f030: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f040: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
f050: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
f060: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
f070: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
f080: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
f090: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
f0a0: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
f0b0: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
f0c0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
f0d0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
f0e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
f0f0: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
f100: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
f110: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
f120: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
f130: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
f140: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
f150: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
f160: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
f170: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
f180: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
f190: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
f1a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
f1b0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
f1c0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
f1d0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
f1e0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
f1f0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
f200: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
f210: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
f220: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
f230: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
f240: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
f250: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
f260: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
f270: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
f280: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
f290: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
f2a0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
f2b0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
f2c0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
f2d0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
f2e0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
f2f0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
f300: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
f310: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
f320: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
f330: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
f340: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
f350: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
f360: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
f370: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
f380: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
f390: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
f3a0: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
f3b0: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
f3c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
f3d0: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
f3e0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
f3f0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
f400: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
f410: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
f420: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
f430: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
f440: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
f450: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
f460: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
f470: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
f480: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 e. The [sqlite3
f490: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
f4a0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
f4b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
f4c0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
f4d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f4e0: 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
f4f0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
f500: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
f510: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
f520: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
f530: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
f540: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
f550: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
f560: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
f570: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
f580: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
f590: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
f5a0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
f5b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
f5c0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
f5d0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
f5e0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
f5f0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
f600: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
f610: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 d as a .** boole
f620: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
f630: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
f640: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
f650: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f660: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 n .** statistics
f670: 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
f680: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
f690: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
f6a0: 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c ed, the .** foll
f6b0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
f6c0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
f6d0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
f6e0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
f6f0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
f700: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
f710: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
f720: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
f730: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
f740: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
f750: 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 limit64()].**
f760: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
f770: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 atus()].** </u
f780: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 l>)^.** ^Memory
f790: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
f7a0: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 stics are enable
f7b0: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c d by default unl
f7c0: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a ess SQLite is.**
f7d0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
f7e0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d SQLITE_DEFAULT_M
f7f0: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 EMSTATUS]=0 in w
f800: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 hich case memory
f810: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 .** allocation s
f820: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
f830: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
f840: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a t..** </dd>.**.*
f850: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
f860: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
f870: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
f880: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
f890: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
f8a0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
f8b0: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
f8c0: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
f8d0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
f8e0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
f8f0: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
f900: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
f910: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
f920: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 which the scrat
f930: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
f940: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
f950: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
f960: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
f970: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
f980: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
f990: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
f9a0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
f9b0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
f9c0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
f9d0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a ultiple of 16..*
f9e0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
f9f0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
fa00: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
fa10: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
fa20: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
fa30: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
fa40: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
fa50: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d te will use no m
fa60: 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 ore than two scr
fa70: 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
fa80: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
fa90: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
faa0: 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 to twice the exp
fab0: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 ected maximum nu
fac0: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e mber of threads.
fad0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
fae0: 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 never require a
faf0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
fb00: 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 that is more tha
fb10: 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 n 6.** times the
fb20: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
fb30: 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ize. ^If SQLite
fb40: 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
fb50: 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
fb60: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
fb70: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
fb80: 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
fb90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
fba0: 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
fbb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
fbc0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
fbd0: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
fbe0: 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ded.</dd>.**.**
fbf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
fc00: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e G_PAGECACHE</dt>
fc10: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
fc20: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
fc30: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
fc40: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
fc50: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
fc60: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 * the database p
fc70: 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 age cache with t
fc80: 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 he default page
fc90: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 cache implemenat
fca0: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 ion. .** This c
fcb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f onfiguration sho
fcc0: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
fcd0: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
fce0: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a n-define page.**
fcf0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
fd00: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 ation is loaded
fd10: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 using the SQLITE
fd20: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f _CONFIG_PCACHE o
fd30: 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
fd40: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
fd50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
fd60: 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
fd70: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
fd80: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
fd90: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
fda0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
fdb0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
fdc0: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
fdd0: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
fde0: 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
fdf0: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
fe00: 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
fe10: 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
fe20: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
fe30: 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
fe40: 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
fe50: 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
fe60: 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
fe70: 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
fe80: 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
fe90: 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
fea0: 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
feb0: 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
fec0: 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
fed0: 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
fee0: 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
fef0: 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
ff00: 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
ff10: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
ff20: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
ff30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
ff40: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
ff50: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
ff60: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
ff70: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
ff80: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
ff90: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
ffa0: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
ffb0: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
ffc0: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
ffd0: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
ffe0: 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
fff0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
10000 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
10010 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
10020 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
10030 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
10040 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
10050 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
10060 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
10070 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
10080 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
10090 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
100a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
100b0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
100c0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
100d0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
100e0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
100f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
10100 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
10110 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
10120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
10130 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
10140 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
10150 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
10160 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
10170 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
10180 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 e.** for all of
10190 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
101a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
101b0 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 eds beyond those
101c0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
101d0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
101e0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
101f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
10200 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
10210 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
10220 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 guments: An 8-by
10230 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
10240 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
10250 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
10260 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
10270 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
10280 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
10290 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
102a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
102b0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
102c0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
102d0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
102e0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
102f0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
10300 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
10310 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
10320 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
10330 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
10340 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
10350 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
10360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
10370 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
10380 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
10390 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
103a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
103b0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
103c0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
103d0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
103e0 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
103f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
10400 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
10410 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
10420 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
10430 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
10440 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
10450 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
10460 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
10470 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
10480 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
10490 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
104a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
104b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
104c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
104d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 fined..** The mi
104e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
104f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 size is capped
10500 61 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 at 2^12. Reasona
10510 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f ble values.** fo
10520 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c r the minimum al
10530 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 location size ar
10540 65 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e e 2^5 through 2^
10550 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 8.</dd>.**.** <d
10560 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
10570 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
10580 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
10590 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
105a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
105b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
105c0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
105d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
105e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
105f0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
10600 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
10610 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
10620 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
10630 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
10640 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 ed in place.** t
10650 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
10660 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
10670 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ite.)^ ^SQLite
10680 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
10690 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f the.** content o
106a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
106b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
106c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 ructure before t
106d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 he call to.** [s
106e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
106f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 returns. ^If SQ
10700 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
10710 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
10720 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
10730 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
10740 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
10750 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
10760 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
10770 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
10780 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
10790 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
107a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
107b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
107c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
107d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
107e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
107f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
10800 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
10810 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
10820 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
10830 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a G_GETMUTEX</dt>.
10840 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
10850 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
10860 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
10870 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
10880 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
10890 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
108a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
108b0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
108c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
108d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
108e0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
108f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
10900 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
10910 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e utex routines.)^
10920 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
10930 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
10940 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
10950 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 ult mutex alloca
10960 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
10970 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
10980 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 used to track mu
10990 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 tex usage for pe
109a0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f rformance.** pro
109b0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e filing or testin
109c0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 g, for example.
109d0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
109e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
109f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
10a00 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
10a10 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
10a20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
10a30 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
10a40 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
10a50 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
10a60 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
10a70 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
10a80 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
10a90 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
10aa0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
10ab0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 IG_GETMUTEX conf
10ac0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10ad0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
10ae0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
10af0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
10b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
10b10 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
10b20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
10b30 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
10b40 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
10b50 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 mine the default
10b60 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
10b70 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f ation for the lo
10b80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
10b90 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 llocator on each
10ba0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
10bb0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
10bc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
10bd0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
10be0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
10bf0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
10c00 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
10c10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
10c20 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 lots allocated t
10c30 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
10c40 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e connection.)^ ^
10c50 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 (This option set
10c60 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 s the.** <i>defa
10c70 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
10c80 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
10c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
10ca0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 KASIDE].** verb
10cb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
10cc0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
10cd0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
10ce0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
10cf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
10d00 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
10d10 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
10d20 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
10d30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c E_CONFIG_PCACHE<
10d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
10d50 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
10d60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
10d70 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
10d80 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b inter to.** an [
10d90 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
10da0 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 ethods] object.
10db0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 This object spe
10dc0 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 cifies the inter
10dd0 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 face.** to a cus
10de0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 tom page cache i
10df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e mplementation.)^
10e00 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ^SQLite makes
10e10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
10e20 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 object and uses
10e30 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 it for page cac
10e40 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
10e50 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a tions.</dd>.**.*
10e60 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
10e70 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 FIG_GETPCACHE</d
10e80 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
10e90 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
10ea0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
10eb0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
10ec0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
10ed0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
10ee0 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 hods] object. S
10ef0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 QLite copies of
10f00 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 the current.** p
10f10 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
10f20 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 entation into th
10f30 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 at object.)^ </d
10f40 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
10f50 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f ITE_CONFIG_LOG</
10f60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
10f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
10f80 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OG option takes
10f90 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 two arguments: a
10fa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a pointer to a.**
10fb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
10fc0 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 call signature
10fd0 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a of void(*)(void*
10fe0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
10ff0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 ), .** and a poi
11000 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 nter to void. ^I
11010 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 f the function p
11020 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
11030 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 LL, it is.** inv
11040 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oked by [sqlite3
11050 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 _log()] to proce
11060 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 ss each logging
11070 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
11080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e ** function poin
11090 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ter is NULL, the
110a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
110b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d interface becom
110c0 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e es a no-op..** ^
110d0 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 The void pointer
110e0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 that is the sec
110f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
11100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
11110 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 G is.** passed t
11120 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 hrough as the fi
11130 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
11140 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
11150 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
11160 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e ** function when
11170 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 ever that functi
11180 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 on is invoked.
11190 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
111a0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
111b0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 logger function
111c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
111d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
111e0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f to the correspo
111f0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 nding.** [sqlite
11200 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 3_log()] call an
11210 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f d is intended to
11220 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f be a [result co
11230 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 de] or an.** [ex
11240 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
11250 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 de]. ^The third
11260 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
11270 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 d to the logger
11280 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 is.** log messag
11290 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 e after formatti
112a0 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f ng via [sqlite3_
112b0 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 snprintf()]..**
112c0 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 The SQLite loggi
112d0 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ng interface is
112e0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 not reentrant; t
112f0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
11300 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 on.** supplied b
11310 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
11320 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b n must not invok
11330 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 e any SQLite int
11340 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 erface..** In a
11350 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 multi-threaded a
11360 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 pplication, the
11370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
11380 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 ned logger.** fu
11390 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 nction must be t
113a0 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e hreadsafe. </dd>
113b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
113c0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 E_CONFIG_URI.**
113d0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e <dd> This option
113e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
113f0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
11400 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 int. If non-zer
11410 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 o, then.** URI h
11420 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
11430 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 lly enabled. If
11440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
11450 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 zero, then URI
11460 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 handling.** is g
11470 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
11480 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e . If URI handlin
11490 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
114a0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
114b0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 ames.** passed t
114c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
114d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
114e0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 n_v2()], [sqlite
114f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
11500 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
11510 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
11520 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
11530 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
11540 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
11550 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
11560 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
11570 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
11580 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
11590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
115a0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 ion is opened. I
115b0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
115c0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
115d0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
115e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
115f0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
11600 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
11610 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
11620 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
11630 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
11640 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 d. By default, U
11650 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
11660 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
11670 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
11680 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
11690 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
116a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
116b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
116c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
116d0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
116e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
116f0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 G_SINGLETHREAD
11700 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 1 /* nil */.#de
11710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
11720 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 IG_MULTITHREAD
11730 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 2 /* nil */.#d
11740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
11750 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 FIG_SERIALIZED
11760 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 3 /* nil */.#
11770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
11780 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 NFIG_MALLOC
11790 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
117a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
117b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
117c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
117d0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
117e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
117f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
11800 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
11810 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 6 /* voi
11820 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
11830 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
11840 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
11850 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 ACHE 7 /* v
11860 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
11870 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
11880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
11890 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a P 8 /*
118a0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 void*, int nByt
118b0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 e, int min */.#d
118c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
118d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 FIG_MEMSTATUS
118e0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 9 /* boolean
118f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
11900 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 E_CONFIG_MUTEX
11910 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 10 /* sql
11920 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
11930 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
11940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
11950 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a MUTEX 11 /*
11960 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
11970 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 ethods* */./* pr
11980 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f eviously SQLITE_
11990 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f CONFIG_CHUNKALLO
119a0 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f C 12 which is no
119b0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 w unused. */ .#d
119c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
119d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
119e0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
119f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
11a00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
11a10 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 14 /* sql
11a20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
11a30 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
11a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
11a50 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f TPCACHE 15 /
11a60 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
11a70 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
11a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
11a90 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
11aa0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
11ab0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
11ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
11ad0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
11ae0 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 int */../*.** C
11af0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
11b00 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
11b10 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
11b20 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
11b30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
11b40 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
11b50 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
11b60 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
11b70 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
11b80 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
11b90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
11ba0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
11bb0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
11bc0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
11bd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
11be0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
11bf0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
11c00 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
11c10 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
11c20 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
11c30 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
11c40 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
11c50 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
11c60 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
11c70 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
11c80 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
11c90 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
11ca0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
11cb0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
11cc0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
11cd0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
11ce0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
11cf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
11d00 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
11d10 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
11d20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11d30 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
11d40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
11d50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
11d60 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
11d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
11d80 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
11d90 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
11da0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
11db0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
11dc0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
11dd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
11de0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
11df0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
11e00 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
11e10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
11e20 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
11e30 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
11e40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
11e50 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
11e60 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
11e70 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
11e80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a okaside memory..
11e90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
11ea0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 gument after the
11eb0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
11ec0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a _LOOKASIDE verb.
11ed0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 ** may be NULL i
11ee0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
11ef0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
11f00 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
11f10 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
11f20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
11f30 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 malloc()]. ^The
11f40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
11f50 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
11f60 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
11f70 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e buffer slot. ^
11f80 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
11f90 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
11fa0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
11fb0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
11fc0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
11fd0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
11fe0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
11ff0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
12000 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
12010 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
12020 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
12030 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
12040 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
12050 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
12060 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 ary. ^If the se
12070 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
12080 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e .** SQLITE_DBCON
12090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 FIG_LOOKASIDE is
120a0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 not a multiple
120b0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 of 8, it is inte
120c0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 rnally.** rounde
120d0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 d down to the ne
120e0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 xt smaller multi
120f0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 ple of 8. ^(The
12100 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
12110 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 y.** configurati
12120 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 on for a databas
12130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e e connection can
12140 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 only be changed
12150 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f when that.** co
12160 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 nnection is not
12170 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 currently using
12180 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
12190 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f , or in other wo
121a0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 rds.** when the
121b0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 "current value"
121c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
121d0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
121e0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e s](D,[SQLITE_CON
121f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e FIG_LOOKASIDE],.
12200 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 ..) is zero..**
12210 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
12220 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
12230 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 ide memory confi
12240 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f guration when lo
12250 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 okaside.** memor
12260 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 y is in use leav
12270 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 es the configura
12280 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 tion unchanged a
12290 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b nd returns .** [
122a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c SQLITE_BUSY].)^<
122b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
122c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
122d0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a NABLE_FKEY</dt>.
122e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
122f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
12300 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
12310 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e e the enforcemen
12320 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e t of.** [foreign
12330 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
12340 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 ]. There should
12350 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
12360 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
12370 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
12380 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
12390 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
123a0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 disable FK enfor
123b0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 cement,.** posit
123c0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b ive to enable FK
123d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 enforcement or
123e0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
123f0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
12400 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 .** unchanged.
12410 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
12420 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
12430 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
12440 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
12450 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
12460 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
12470 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 her FK enforceme
12480 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a nt is off or on.
12490 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
124a0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
124b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
124c0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
124d0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
124e0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 case the FK enf
124f0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 orcement setting
12500 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
12510 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
12520 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
12530 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
12540 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 IGGER</dt>.** <d
12550 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
12560 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
12570 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 e or disable [CR
12580 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
12590 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 riggers]..** The
125a0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
125b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
125c0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
125d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
125e0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
125f0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
12600 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f triggers,.** po
12610 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
12620 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 triggers or neg
12630 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
12640 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
12650 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
12660 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
12670 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
12680 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
12690 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
126a0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
126b0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 cate whether tri
126c0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c ggers are disabl
126d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
126e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
126f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
12700 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
12710 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
12720 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
12730 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ase the trigger
12740 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
12750 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
12760 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
12770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
12780 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
12790 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 SIDE 1001
127a0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
127b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
127c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
127d0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 BLE_FKEY 100
127e0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2 /* int int* *
127f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12800 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
12810 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 _TRIGGER 1003
12820 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
12830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12840 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
12850 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
12860 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e lt Codes.**.** ^
12870 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
12880 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
12890 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
128a0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
128b0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
128c0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
128d0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
128e0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
128f0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
12900 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
12910 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
12920 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
12930 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
12940 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
12950 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
12960 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
12970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12980 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
12990 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 wid.**.** ^Each
129a0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 entry in an SQLi
129b0 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 te table has a u
129c0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 nique 64-bit sig
129d0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b ned.** integer k
129e0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 ey called the [R
129f0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e OWID | "rowid"].
12a00 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 ^The rowid is a
12a10 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a lways available.
12a20 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 ** as an undecla
12a30 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 red column named
12a40 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
12a50 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 _ROWID_ as long
12a60 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 as those.** name
12a70 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 s are not also u
12a80 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c sed by explicitl
12a90 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
12aa0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 ns. ^If.** the t
12ab0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d able has a colum
12ac0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 n of type [INTEG
12ad0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
12ae0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e then that column
12af0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 .** is another a
12b00 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 lias for the row
12b10 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 id..**.** ^This
12b20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
12b30 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
12b40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a he most recent.*
12b50 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
12b60 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 SERT] into the d
12b70 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 atabase from the
12b80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12b90 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 ction].** in the
12ba0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
12bb0 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 ^If no success
12bc0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a ful [INSERT]s.**
12bd0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
12be0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 red on that data
12bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
12c00 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 zero is returne
12c10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e d..**.** ^(If an
12c20 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 [INSERT] occurs
12c30 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
12c40 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 r, then the [row
12c50 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 id] of the inser
12c60 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 ted.** row is re
12c70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
12c80 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 outine as long a
12c90 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 s the trigger is
12ca0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
12cb0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
12cc0 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 r terminates, th
12cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
12ce0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
12cf0 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 .** reverts to t
12d00 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e he last value in
12d10 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 serted before th
12d20 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e e trigger fired.
12d30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e )^.**.** ^An [IN
12d40 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
12d50 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
12d60 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
12d70 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
12d80 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
12d90 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
12da0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
12db0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
12dc0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 routine. ^Thus
12dd0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c INSERT OR FAIL,
12de0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 INSERT OR IGNOR
12df0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c E, INSERT OR ROL
12e00 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e LBACK,.** and IN
12e10 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 SERT OR ABORT ma
12e20 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f ke no changes to
12e30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
12e40 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 e of this.** rou
12e50 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 tine when their
12e60 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e insertion fails.
12e70 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 ^(When INSERT
12e80 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e OR REPLACE.** en
12e90 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 counters a const
12ea0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c raint violation,
12eb0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 it does not fai
12ec0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 l. The.** INSER
12ed0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 T continues to c
12ee0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 ompletion after
12ef0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 deleting rows th
12f00 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 at caused.** the
12f10 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 constraint prob
12f20 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 lem so INSERT OR
12f30 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c REPLACE will al
12f40 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 ways change.** t
12f50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
12f60 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
12f70 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 e.)^.**.** ^For
12f80 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
12f90 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
12fa0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
12fb0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
12fc0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
12fd0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
12fe0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
12ff0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ck..**.** This f
13000 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 unction is acces
13010 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 sible to SQL sta
13020 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a tements via the.
13030 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f ** [last_insert_
13040 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 rowid() SQL func
13050 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
13060 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
13070 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
13080 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 [INSERT] on the
13090 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 same.** databas
130a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 e connection whi
130b0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
130c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
130d0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e d()].** function
130e0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
130f0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
13100 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
13110 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 wid],.** then th
13120 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
13130 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 by [sqlite3_las
13140 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
13150 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 ] is.** unpredic
13160 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
13170 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
13180 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
13190 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 new.** last inse
131a0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 rt [rowid]..*/.s
131b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
131c0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
131d0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 _rowid(sqlite3*)
131e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
131f0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d F: Count The Num
13200 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 ber Of Rows Modi
13210 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 fied.**.** ^This
13220 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
13230 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
13240 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 database rows th
13250 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a at were changed.
13260 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f ** or inserted o
13270 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 r deleted by the
13280 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
13290 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 ompleted SQL sta
132a0 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 tement.** on the
132b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
132c0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
132d0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 by the first pa
132e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e rameter..** ^(On
132f0 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 ly changes that
13300 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 are directly spe
13310 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 cified by the [I
13320 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
13330 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d ,.** or [DELETE]
13340 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 statement are c
13350 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 ounted. Auxilia
13360 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ry changes cause
13370 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 d by.** triggers
13380 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 or [foreign key
13390 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f actions] are no
133a0 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 t counted.)^ Use
133b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
133c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
133d0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 ] function to fi
133e0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d nd the total num
133f0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a ber of changes.*
13400 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e * including chan
13410 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 ges caused by tr
13420 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 iggers and forei
13430 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a gn key actions..
13440 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 **.** ^Changes t
13450 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 o a view that ar
13460 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 e simulated by a
13470 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 n [INSTEAD OF tr
13480 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f igger].** are no
13490 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 t counted. Only
134a0 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e real table chan
134b0 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e ges are counted.
134c0 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 .**.** ^(A "row
134d0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 change" is a cha
134e0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 nge to a single
134f0 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 row of a single
13500 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 table.** caused
13510 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 by an INSERT, DE
13520 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 LETE, or UPDATE
13530 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 statement. Rows
13540 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 that.** are cha
13550 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 nged as side eff
13560 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 ects of [REPLACE
13570 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 ] constraint res
13580 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c olution,.** roll
13590 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 back, ABORT proc
135a0 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 essing, [DROP TA
135b0 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 BLE], or by any
135c0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 other.** mechani
135d0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 sms do not count
135e0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 as direct row c
135f0 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 hanges.)^.**.**
13600 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 A "trigger conte
13610 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f xt" is a scope o
13620 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 f execution that
13630 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 begins and.** e
13640 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 nds with the scr
13650 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 ipt of a [CREATE
13660 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
13670 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 er]. .** Most SQ
13680 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
13690 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 .** evaluated ou
136a0 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 tside of any tri
136b0 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 gger. This is t
136c0 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a he "top level".*
136d0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
136e0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 t. If a trigger
136f0 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 fires from the
13700 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 top level, a.**
13710 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
13720 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 ext is entered f
13730 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 or the duration
13740 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 of that one.** t
13750 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 rigger. Subtrig
13760 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 gers create subc
13770 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 ontexts for thei
13780 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a r duration..**.*
13790 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 * ^Calling [sqli
137a0 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b te3_exec()] or [
137b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
137c0 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 recursively does
137d0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 .** not create a
137e0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e new trigger con
137f0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 text..**.** ^Thi
13800 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
13810 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
13820 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e direct row chan
13830 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f ges in the.** mo
13840 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
13850 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
13860 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
13870 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a thin the same.**
13880 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
13890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 ..**.** ^Thus, w
138a0 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 hen called from
138b0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 the top level, t
138c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
138d0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 urns the.** numb
138e0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e er of changes in
138f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
13900 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
13910 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
13920 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 at also occurred
13930 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 at the top leve
13940 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 l. ^(Within the
13950 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 body of a trigg
13960 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 er,.** the sqlit
13970 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 e3_changes() int
13980 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 erface can be ca
13990 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 lled to find the
139a0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
139b0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
139c0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
139d0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 eted INSERT, UPD
139e0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
139f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 * statement with
13a00 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 in the body of t
13a10 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
13a20 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
13a30 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 number returned
13a40 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
13a50 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 e changes.** cau
13a60 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 sed by subtrigge
13a70 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 rs since those h
13a80 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f ave their own co
13a90 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 ntext.)^.**.** S
13aa0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
13ab0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
13ac0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
13ad0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
13ae0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
13af0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 and the [changes
13b00 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
13b10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
13b20 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
13b30 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
13b40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
13b50 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 connection.** wh
13b60 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 ile [sqlite3_cha
13b70 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
13b80 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
13b90 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 e returned.** is
13ba0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
13bb0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
13bc0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
13bd0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 3_changes(sqlite
13be0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
13bf0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 3REF: Total Numb
13c00 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
13c10 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ied.**.** ^This
13c20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
13c30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
13c40 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ow changes cause
13c50 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a d by [INSERT],.*
13c60 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 * [UPDATE] or [D
13c70 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
13c80 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 s since the [dat
13c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13ca0 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a ] was opened..**
13cb0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 ^(The count ret
13cc0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
13cd0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
13ce0 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 includes all ch
13cf0 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c anges.** from al
13d00 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 l [CREATE TRIGGE
13d10 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e R | trigger] con
13d20 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 texts and change
13d30 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f s made by.** [fo
13d40 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
13d50 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 s]. However,.**
13d60 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e the count does n
13d70 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
13d80 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 es used to imple
13d90 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 ment [REPLACE] c
13da0 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 onstraints,.** d
13db0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 o rollbacks or A
13dc0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
13dd0 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d or [DROP TABLE]
13de0 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 processing. Th
13df0 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 e.** count does
13e00 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 not include rows
13e10 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 of views that f
13e20 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 ire an [INSTEAD
13e30 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 OF trigger],.**
13e40 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e though if the IN
13e50 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
13e60 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
13e70 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 f its own, those
13e80 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 changes .** are
13e90 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e counted.)^.** ^
13ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 The sqlite3_tota
13eb0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 l_changes() func
13ec0 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 tion counts the
13ed0 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 changes as soon
13ee0 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d as.** the statem
13ef0 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 ent that makes t
13f00 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 hem is completed
13f10 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 (when the state
13f20 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 ment handle.** i
13f30 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
13f40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
13f50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
13f60 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 ze()])..**.** Se
13f70 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
13f80 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
13f90 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
13fa0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
13fb0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
13fc0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 [total_changes(
13fd0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
13fe0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
13ff0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
14000 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
14010 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
14020 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
14030 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
14040 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
14050 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
14060 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
14070 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
14080 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
14090 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
140a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
140b0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
140c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
140d0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
140e0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a g-Running Query.
140f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
14100 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
14110 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
14120 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
14130 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
14140 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
14150 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
14160 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
14170 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
14180 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
14190 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
141a0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
141b0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
141c0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
141d0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
141e0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
141f0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
14200 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
14210 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 ^It is safe to
14220 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
14230 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
14240 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
14250 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
14260 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
14270 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
14280 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
14290 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
142a0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
142b0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
142c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
142d0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
142e0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
142f0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
14300 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
14310 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
14320 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 ** ^If an SQL op
14330 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
14340 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
14350 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
14360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
14370 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
14380 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
14390 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
143a0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
143b0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
143c0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
143d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
143e0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 **.** ^An SQL op
143f0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 eration that is
14400 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c interrupted will
14410 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
14420 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e INTERRUPT]..** ^
14430 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
14440 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
14450 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
14460 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
14470 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
14480 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
14490 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
144a0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
144b0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
144c0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
144d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
144e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
144f0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 _interrupt(D) ca
14500 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 ll is in effect
14510 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e until all curren
14520 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 tly running.** S
14530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e QL statements on
14540 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
14550 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 ction] D complet
14560 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c e. ^Any new SQL
14570 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
14580 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
14590 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
145a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
145b0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ll and before th
145c0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 e .** running st
145d0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 atements reaches
145e0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 zero are interr
145f0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 upted as if they
14600 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e had been.** run
14610 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 ning prior to th
14620 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
14630 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 upt() call. ^Ne
14640 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
14650 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
14660 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 rted after the r
14670 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
14680 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a count reaches z
14690 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 ero are.** not e
146a0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 ffected by the s
146b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
146c0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 ()..** ^A call t
146d0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 o sqlite3_interr
146e0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 upt(D) that occu
146f0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 rs when there ar
14700 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 e no running.**
14710 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
14720 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 s a no-op and ha
14730 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 s no effect on S
14740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
14750 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
14760 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
14770 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
14780 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a call returns..**
14790 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
147a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
147b0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
147c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
147d0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
147e0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
147f0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
14800 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 en..*/.void sqli
14810 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 te3_interrupt(sq
14820 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
14830 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
14840 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
14850 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c atement Is Compl
14860 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ete.**.** These
14870 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
14880 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 ful during comma
14890 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f nd-line input to
148a0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 determine if th
148b0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 e.** currently e
148c0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d ntered text seem
148d0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 s to form a comp
148e0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
148f0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 nt or.** if addi
14900 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 tional input is
14910 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 needed before se
14920 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 nding the text i
14930 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f nto.** SQLite fo
14940 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 r parsing. ^The
14950 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
14960 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 rn 1 if the inpu
14970 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
14980 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
14990 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
149a0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e nt. ^A statemen
149b0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 t is judged to b
149c0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 e.** complete if
149d0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 it ends with a
149e0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 semicolon token
149f0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 and is not a pre
14a00 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c fix of a.** well
14a10 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 -formed CREATE T
14a20 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
14a30 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 . ^Semicolons t
14a40 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 hat are embedded
14a50 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e within.** strin
14a60 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 g literals or qu
14a70 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 oted identifier
14a80 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 names or comment
14a90 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 s are not.** ind
14aa0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 ependent tokens
14ab0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f (they are part o
14ac0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 f the token in w
14ad0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a hich they are.**
14ae0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 embedded) and t
14af0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 hus do not count
14b00 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 as a statement
14b10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 terminator. ^Wh
14b20 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 itespace.** and
14b30 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f comments that fo
14b40 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 llow the final s
14b50 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e emicolon are ign
14b60 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ored..**.** ^The
14b70 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
14b80 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 rn 0 if the stat
14b90 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c ement is incompl
14ba0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d ete. ^If a.** m
14bb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14bc0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c fails, then SQL
14bd0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 ITE_NOMEM is ret
14be0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
14bf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 ese routines do
14c00 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 not parse the SQ
14c10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 L statements thu
14c20 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 s.** will not de
14c30 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c tect syntactical
14c40 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c ly incorrect SQL
14c50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c ..**.** ^(If SQL
14c60 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ite has not been
14c70 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 initialized usi
14c80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ng [sqlite3_init
14c90 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 ialize()] prior
14ca0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 .** to invoking
14cb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
14cc0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 16() then sqlite
14cd0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
14ce0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 s invoked.** aut
14cf0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
14d00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
14d10 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 (). If that ini
14d20 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c tialization fail
14d30 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 s,.** then the r
14d40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
14d50 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
14d60 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f e16() will be no
14d70 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 n-zero.** regard
14d80 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
14d90 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 or not the input
14da0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 SQL is complete
14db0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e .)^.**.** The in
14dc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
14dd0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 complete()] must
14de0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
14df0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 nated.** UTF-8 s
14e00 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
14e10 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
14e20 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
14e30 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
14e40 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
14e50 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
14e60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
14e70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
14e80 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 _complete(const
14e90 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 char *sql);.int
14ea0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
14eb0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 16(const void *s
14ec0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ql);../*.** CAPI
14ed0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
14ee0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e Callback To Han
14ef0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 dle SQLITE_BUSY
14f00 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 Errors.**.** ^Th
14f10 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
14f20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
14f30 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 ion that might b
14f40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
14f50 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
14f60 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
14f70 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
14f80 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
14f90 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 hread.** or proc
14fa0 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a ess has locked..
14fb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 **.** ^If the bu
14fc0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
14fd0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ULL, then [SQLIT
14fe0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
14ff0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
15000 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
15010 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f immediately upo
15020 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 n encountering t
15030 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 he lock. ^If th
15040 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a e busy callback.
15050 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 ** is not NULL,
15060 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 then the callbac
15070 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b k might be invok
15080 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 ed with two argu
15090 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
150a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
150b0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e to the busy han
150c0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f dler is a copy o
150d0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e f the void* poin
150e0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
150f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
15100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 nt to sqlite3_bu
15110 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e sy_handler(). ^
15120 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
15130 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 ent to.** the bu
15140 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy handler callb
15150 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
15160 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
15170 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
15180 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
15190 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f oked for this lo
151a0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 cking event. ^I
151b0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 f the.** busy ca
151c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 llback returns 0
151d0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 , then no additi
151e0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 onal attempts ar
151f0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 e made to.** acc
15200 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
15210 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 and [SQLITE_BUS
15220 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
15230 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 ERR_BLOCKED] is
15240 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 returned..** ^If
15250 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
15260 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
15270 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
15280 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
15290 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
152a0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 base for reading
152b0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 and the cycle r
152c0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 epeats..**.** Th
152d0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 e presence of a
152e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 busy handler doe
152f0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 s not guarantee
15300 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 that it will be
15310 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 invoked.** when
15320 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f there is lock co
15330 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 ntention. ^If SQ
15340 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 Lite determines
15350 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 that invoking th
15360 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 e busy.** handle
15370 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 r could result i
15380 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 n a deadlock, it
15390 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 will go ahead a
153a0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
153b0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 E_BUSY].** or [S
153c0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
153d0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 KED] instead of
153e0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
153f0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f y handler..** Co
15400 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 nsider a scenari
15410 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 o where one proc
15420 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
15430 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a read lock that.
15440 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 ** it is trying
15450 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 to promote to a
15460 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e reserved lock an
15470 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 d.** a second pr
15480 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
15490 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
154a0 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 that it is tryi
154b0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 ng.** to promote
154c0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 to an exclusive
154d0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 lock. The firs
154e0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 t process cannot
154f0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 proceed.** beca
15500 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
15510 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
15520 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 and the second p
15530 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a rocess cannot.**
15540 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 proceed because
15550 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
15560 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 y the first. If
15570 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a both processes.
15580 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 ** invoke the bu
15590 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 sy handlers, nei
155a0 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 ther will make a
155b0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 ny progress. Th
155c0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 erefore,.** SQLi
155d0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 te returns [SQLI
155e0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 TE_BUSY] for the
155f0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 first process,
15600 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 hoping that this
15610 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 .** will induce
15620 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
15630 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 s to release its
15640 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 read lock and a
15650 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f llow.** the seco
15660 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 nd process to pr
15670 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 oceed..**.** ^Th
15680 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 e default busy c
15690 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e allback is NULL.
156a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
156b0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 ITE_BUSY] error
156c0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 is converted to
156d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
156e0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 OCKED].** when S
156f0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 QLite is in the
15700 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 middle of a larg
15710 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 e transaction wh
15720 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 ere all the.** c
15730 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 hanges will not
15740 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d fit into the in-
15750 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 memory cache. S
15760 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c QLite will.** al
15770 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 ready hold a RES
15780 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 ERVED lock on th
15790 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
157a0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a but it needs.**
157b0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 to promote this
157c0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 lock to EXCLUSI
157d0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 VE so that it ca
157e0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a n spill cache.**
157f0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 pages into the
15800 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
15810 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f thout harm to co
15820 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 ncurrent.** read
15830 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 ers. ^If it is
15840 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 unable to promot
15850 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e e the lock, then
15860 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a the in-memory.*
15870 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 * cache will be
15880 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e left in an incon
15890 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e sistent state an
158a0 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a d so the error.*
158b0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 * code is promot
158c0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 ed from the rela
158d0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 tively benign [S
158e0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a QLITE_BUSY] to.*
158f0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 * the more sever
15900 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f e [SQLITE_IOERR_
15910 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 BLOCKED]. ^This
15920 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d error code prom
15930 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 otion.** forces
15940 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c an automatic rol
15950 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 lback of the cha
15960 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a nges. See the.*
15970 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 * <a href="/cvst
15980 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 rac/wiki?p=Corru
15990 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
159a0 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 syError">.** Cor
159b0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
159c0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 BusyError</a> wi
159d0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 ki page for a di
159e0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a scussion of why.
159f0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 ** this is impor
15a00 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 tant..**.** ^(Th
15a10 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
15a20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
15a30 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f ndler defined fo
15a40 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 r each.** [datab
15a50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
15a60 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 Setting a new
15a70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 busy handler cle
15a80 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 ars any.** previ
15a90 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 ously set handle
15aa0 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 r.)^ ^Note that
15ab0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
15ac0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
15ad0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 ].** will also s
15ae0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 et or clear the
15af0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
15b00 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c .** The busy cal
15b10 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 lback should not
15b20 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e take any action
15b30 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 s which modify t
15b40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
15b50 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
15b60 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
15b70 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 handler. Any su
15b80 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 ch actions.** re
15b90 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
15ba0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a d behavior..** .
15bb0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 ** A busy handle
15bc0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 r must not close
15bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
15be0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b nnection.** or [
15bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
15c00 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 nt] that invoked
15c10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
15c20 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
15c30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
15c40 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
15c50 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 void*,int), void
15c60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
15c70 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 REF: Set A Busy
15c80 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 Timeout.**.** ^T
15c90 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 his routine sets
15ca0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 a [sqlite3_busy
15cb0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 _handler | busy
15cc0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c handler] that sl
15cd0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 eeps.** for a sp
15ce0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f ecified amount o
15cf0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 f time when a ta
15d00 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 ble is locked.
15d10 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 ^The handler.**
15d20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 will sleep multi
15d30 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 ple times until
15d40 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
15d50 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
15d60 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 eeping.** have a
15d70 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 ccumulated. ^Af
15d80 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 ter at least "ms
15d90 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
15da0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 f sleeping,.** t
15db0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 he handler retur
15dc0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 ns 0 which cause
15dd0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 s [sqlite3_step(
15de0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 )] to return.**
15df0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
15e00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
15e10 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e LOCKED]..**.** ^
15e20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
15e30 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
15e40 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
15e50 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
15e60 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
15e70 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
15e80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 .**.** ^(There c
15e90 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
15ea0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
15eb0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
15ec0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
15ed0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 onnection] any a
15ee0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e ny given moment.
15ef0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
15f00 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 y handler.** was
15f10 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 defined (using
15f20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
15f30 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
15f40 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
15f50 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
15f60 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
15f70 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
15f80 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )^.*/.int sqlite
15f90 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 3_busy_timeout(s
15fa0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 qlite3*, int ms)
15fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
15fc0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 F: Convenience R
15fd0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e outines For Runn
15fe0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a ing Queries.**.*
15ff0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 * This is a lega
16000 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 cy interface tha
16010 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 t is preserved f
16020 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
16030 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 patibility..** U
16040 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 se of this inter
16050 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f face is not reco
16060 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 mmended..**.** D
16070 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
16080 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
16090 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
160a0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
160b0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
160c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
160d0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
160e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
160f0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
16100 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
16110 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
16120 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
16130 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
16140 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
16150 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
16160 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
16170 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
16180 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
16190 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
161a0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
161b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
161c0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
161d0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
161e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
161f0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
16200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
16210 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
16220 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
16230 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
16240 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
16250 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
16260 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
16270 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
16280 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
16290 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
162a0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
162b0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
162c0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
162d0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
162e0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
162f0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
16300 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
16310 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
16320 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
16330 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
16340 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
16350 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
16360 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
16370 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
16380 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
16390 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
163a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
163b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
163c0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
163d0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
163e0 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
163f0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
16400 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
16410 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
16420 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
16430 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
16440 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
16450 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
16460 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
16470 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
16480 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
16490 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
164a0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 ^(As an example
164b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
164c0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 ble format, supp
164d0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 ose a query resu
164e0 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c lt.** is as foll
164f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
16500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
16510 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 Name
16520 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 | Age.**
16530 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -------------
16540 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 ----------.**
16550 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 Alice
16560 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 | 43.**
16570 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 Bob | 28
16580 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 .** Cindy
16590 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c | 21.** <
165a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
165b0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 e>.**.** There a
165c0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d re two column (M
165d0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 ==2) and three r
165e0 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 ows (N==3). Thu
165f0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 s the.** result
16600 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 table has 8 entr
16610 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 ies. Suppose th
16620 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
16630 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
16640 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a n array names az
16650 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a Result. Then az
16660 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 Result holds thi
16670 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a s content:.**.**
16680 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
16690 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 e>.** azR
166a0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 esult[0] = "
166b0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 Name";.**
166c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d azResult[1]
166d0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 = "Age";.**
166e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
166f0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a ;2] = "Alice";.*
16700 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
16710 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b t[3] = "43";
16720 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
16730 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f ult[4] = "Bo
16740 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a b";.** az
16750 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 Result[5] =
16760 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "28";.**
16770 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 azResult[6]
16780 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 = "Cindy";.**
16790 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
167a0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 1;7] = "21";.**
167b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
167c0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te>)^.**.** ^The
167d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
167e0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 le() function ev
167f0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d aluates one or m
16800 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ore.** semicolon
16810 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 -separated SQL s
16820 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
16830 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
16840 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 UTF-8.** string
16850 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 of its 2nd para
16860 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
16870 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
16880 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
16890 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
168a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
168b0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 *.** After the a
168c0 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 pplication has f
168d0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 inished with the
168e0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c result from sql
168f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
16900 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 ,.** it must pas
16910 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 s the result tab
16920 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 le pointer to sq
16930 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
16940 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a () in order to.*
16950 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
16960 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
16970 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 lloced. Because
16980 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a of the way the.
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
169a0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 oc()] happens wi
169b0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 thin sqlite3_get
169c0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 _table(), the ca
169d0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f lling.** functio
169e0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 n must not try t
169f0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f o call [sqlite3_
16a00 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 free()] directly
16a10 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 . Only.** [sqli
16a20 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
16a30 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
16a40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
16a50 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
16a60 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
16a70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
16a80 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
16a90 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
16aa0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
16ab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
16ac0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
16ad0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
16ae0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
16af0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
16b00 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
16b10 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
16b20 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
16b30 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
16b40 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
16b50 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
16b60 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
16b70 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
16b80 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
16b90 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
16ba0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
16bb0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
16bc0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
16bd0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
16be0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
16bf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
16c00 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 code()] or.** [s
16c10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
16c20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
16c30 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
16c40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
16c50 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
16c60 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
16c70 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
16c80 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
16c90 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
16ca0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
16cb0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
16cc0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
16cd0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
16ce0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
16cf0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
16d00 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
16d10 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
16d20 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
16d30 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
16d40 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
16d50 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
16d60 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
16d70 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
16d80 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 n here */.);.voi
16d90 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 d sqlite3_free_t
16da0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
16db0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
16dc0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
16dd0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
16de0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
16df0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
16e00 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f re work-alikes o
16e10 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 f the "printf()"
16e20 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 family of funct
16e30 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ions.** from the
16e40 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
16e50 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ary..**.** ^The
16e60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
16e70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
16e80 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
16e90 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
16ea0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
16eb0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
16ec0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
16ed0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
16ee0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
16ef0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
16f00 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
16f10 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
16f20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
16f30 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 ^Both routines
16f40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c return a.** NULL
16f50 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c pointer if [sql
16f60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
16f70 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
16f80 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d cate enough.** m
16f90 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
16fa0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
16fb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ng..**.** ^(The
16fc0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
16fd0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
16fe0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e milar to "snprin
16ff0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 tf()" from.** th
17000 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
17010 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c rary. The resul
17020 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 t is written int
17030 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 o the.** buffer
17040 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 supplied as the
17050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17060 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 whose size is g
17070 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 iven by.** the f
17080 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 irst parameter.
17090 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 Note that the or
170a0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 der of the.** fi
170b0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 rst two paramete
170c0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 rs is reversed f
170d0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 rom snprintf().)
170e0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a ^ This is an.**
170f0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
17100 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
17110 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
17120 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
17130 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
17140 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 ility. ^(Note a
17150 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
17160 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
17170 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
17180 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
17190 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
171a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
171b0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
171c0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
171d0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 buffer.)^ We ad
171e0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
171f0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
17200 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
17210 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
17220 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
17230 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
17240 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
17250 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
17260 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
17270 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
17280 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
17290 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e ibility..**.** ^
172a0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
172b0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
172c0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
172d0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
172e0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
172f0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
17300 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
17310 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
17320 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
17330 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
17340 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
17350 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
17360 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
17370 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
17380 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
17390 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
173a0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
173b0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
173c0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
173d0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 acters..**.** ^T
173e0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 he sqlite3_vsnpr
173f0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
17400 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 s a varargs vers
17410 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
17420 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a nprintf()..**.**
17430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
17440 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f all implement so
17450 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f me additional fo
17460 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 rmatting.** opti
17470 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 ons that are use
17480 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 ful for construc
17490 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 ting SQL stateme
174a0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 nts..** All of t
174b0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 he usual printf(
174c0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 ) formatting opt
174d0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 ions apply. In
174e0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a addition, there.
174f0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 ** is are "%q",
17500 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f "%Q", and "%z" o
17510 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ptions..**.** ^(
17520 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f The %q option wo
17530 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 rks like %s in t
17540 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 hat it substitut
17550 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e es a null-termin
17560 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
17570 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
17580 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
17590 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
175a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
175b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
175c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
175d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
175e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
175f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
17600 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
17610 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
17620 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
17630 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
17640 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
17650 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
17660 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
17670 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
17680 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
17690 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
176a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
176b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
176c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
176d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
176e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
176f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
17700 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
17710 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
17720 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
17730 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
17740 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
17750 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
17760 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
17770 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
17780 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
17790 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
177a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
177b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
177c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
177d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
177e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
177f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
17800 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
17810 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
17820 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
17830 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
17840 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
17850 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
17860 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
17870 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
17880 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
17890 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
178a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
178b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
178c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
178d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
178e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
178f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
17900 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
17910 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
17920 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
17930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
17940 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
17950 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
17960 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
17970 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
17980 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
17990 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
179a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
179b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
179c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
179d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
179e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
179f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
17a00 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
17a10 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
17a20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
17a30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
17a40 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
17a50 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
17a60 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
17a70 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
17a80 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
17a90 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
17aa0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
17ab0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
17ac0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
17ad0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
17ae0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
17af0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
17b00 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
17b10 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
17b20 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
17b30 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
17b40 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
17b50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
17b60 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
17b70 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
17b80 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
17b90 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
17ba0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
17bb0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
17bc0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
17bd0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
17be0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
17bf0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
17c00 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
17c10 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
17c20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
17c30 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
17c40 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
17c50 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
17c60 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
17c70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
17c80 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 .** ^(The "%z" f
17c90 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
17ca0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 works like "%s"
17cb0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a but with the.**
17cc0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 addition that a
17cd0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 fter the string
17ce0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e has been read an
17cf0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a d copied into.**
17d00 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 the result, [sq
17d10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
17d20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 called on the i
17d30 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a nput string.)^.*
17d40 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
17d50 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
17d60 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
17d70 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
17d80 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
17d90 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 _list);.char *sq
17da0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
17db0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
17dc0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 har*, ...);.char
17dd0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 *sqlite3_vsnpri
17de0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
17df0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
17e00 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 st);../*.** CAPI
17e10 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
17e20 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
17e30 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
17e40 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
17e50 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
17e60 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
17e70 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
17e80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
17e90 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
17ea0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
17eb0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
17ec0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
17ed0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
17ee0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
17ef0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
17f00 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
17f10 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
17f20 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
17f30 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
17f40 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
17f50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
17f60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
17f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
17f80 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
17f90 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
17fa0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
17fb0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
17fc0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
17fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
17fe0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
17ff0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
18000 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
18010 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
18020 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
18030 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
18040 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
18050 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
18060 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
18070 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
18080 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
18090 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
180a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
180b0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
180c0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
180d0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
180e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
180f0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
18100 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
18110 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
18120 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
18130 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
18140 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
18150 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
18160 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
18170 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
18180 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
18190 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
181a0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
181b0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
181c0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
181d0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
181e0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
181f0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
18200 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
18210 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
18220 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
18230 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
18240 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
18250 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
18260 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
18270 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
18280 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
18290 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
182a0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
182b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
182c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
182d0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
182e0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
182f0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
18300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
18310 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
18320 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
18330 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 oc()..**.** ^(Th
18340 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
18350 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
18360 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
18370 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
18380 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
18390 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
183a0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
183b0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
183c0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
183d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
183e0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
183f0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
18400 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 arameter.)^ ^ If
18410 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
18420 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
18430 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
18440 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
18450 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
18460 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
18470 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
18480 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
18490 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
184a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
184b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
184c0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 ()..** ^If the s
184d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
184e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
184f0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a oc() is zero or.
18500 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
18510 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
18520 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
18530 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
18540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 sqlite3_free(P)
18550 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 where P is the f
18560 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
18570 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
18580 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 c()..** ^sqlite3
18590 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
185a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
185b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
185c0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
185d0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
185e0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
185f0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
18600 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
18610 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 ** ^If M is the
18620 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
18630 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
18640 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
18650 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
18660 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
18670 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
18680 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
18690 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
186a0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
186b0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
186c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
186d0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
186e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
186f0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
18700 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
18710 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
18720 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
18730 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
18740 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
18750 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
18760 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
18770 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
18780 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
18790 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
187a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
187b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
187c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
187d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
187e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
187f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
18800 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
18810 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
18820 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
18830 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
18840 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
18850 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
18860 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
18870 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
18880 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
18890 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
188a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
188b0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
188c0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
188d0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
188e0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
188f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
18900 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
18910 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 be used..**.** T
18920 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
18930 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
18940 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 lls.** the syste
18950 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
18960 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
18970 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
18980 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
18990 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
189a0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
189b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
189c0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
189d0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
189e0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
189f0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
18a00 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
18a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
18a20 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 rors are detecte
18a30 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 d, but.** they a
18a40 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b re reported back
18a50 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 as [SQLITE_CANT
18a60 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c OPEN] or.** [SQL
18a70 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 ITE_IOERR] rathe
18a80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e r than [SQLITE_N
18a90 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 OMEM]..**.** The
18aa0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
18ab0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ts to [sqlite3_f
18ac0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ree()] and [sqli
18ad0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
18ae0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 * must be either
18af0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f NULL or else po
18b00 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 inters obtained
18b10 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 from a prior.**
18b20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
18b30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18b40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
18b50 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 lloc()] that hav
18b60 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 e.** not yet bee
18b70 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a n released..**.*
18b80 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
18b90 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 n must not read
18ba0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 or write any par
18bb0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 t of.** a block
18bc0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 of memory after
18bd0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 it has been rele
18be0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ased using.** [s
18bf0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f qlite3_free()] o
18c00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
18c10 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a oc()]..*/.void *
18c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 sqlite3_malloc(i
18c30 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 nt);.void *sqlit
18c40 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a e3_realloc(void*
18c50 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
18c60 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 ite3_free(void*)
18c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18c80 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
18c90 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a tor Statistics.*
18ca0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
18cb0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
18cc0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
18cd0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
18ce0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
18cf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18d00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
18d10 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
18d20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
18d30 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
18d40 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
18d50 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
18d60 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
18d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
18d80 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
18d90 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
18da0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
18db0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d bytes.** of mem
18dc0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
18dd0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
18de0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
18df0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c d)..** ^The [sql
18e00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
18e10 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 water()] routine
18e20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 returns the max
18e30 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 imum.** value of
18e40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18e50 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
18e60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
18e70 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 rk.** was last r
18e80 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 eset. ^The valu
18e90 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
18ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
18eb0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 sed()] and.** [s
18ec0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
18ed0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
18ee0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
18ef0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 ** added by SQLi
18f00 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d te in its implem
18f10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c entation of [sql
18f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a ite3_malloc()],.
18f30 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 ** but not overh
18f40 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 ead added by the
18f50 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 any underlying
18f60 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a system library.*
18f70 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
18f80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18f90 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a )] may call..**.
18fa0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 ** ^The memory h
18fb0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 igh-water mark i
18fc0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 s reset to the c
18fd0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a urrent value of.
18fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
18ff0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
19000 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
19010 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
19020 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
19030 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
19040 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 ue. ^The value
19050 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b returned.** by [
19060 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
19070 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
19080 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
19090 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ark.** prior to
190a0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 the reset..*/.sq
190b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
190c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
190d0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 void);.sqlite3_i
190e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
190f0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
19100 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
19110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
19120 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
19130 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
19140 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
19150 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
19160 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
19170 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
19180 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
19190 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
191a0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
191b0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
191c0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
191d0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
191e0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
191f0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
19200 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
19210 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
19220 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
19230 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
19240 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
19250 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
19260 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
19270 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
19280 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
19290 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
192a0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
192b0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
192c0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
192d0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
192e0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
192f0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
19300 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
19310 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e time this routin
19320 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 e is invoked (ei
19330 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 ther internally
19340 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 or by.** the app
19350 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 lication) the PR
19360 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 NG is seeded usi
19370 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 ng randomness ob
19380 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 tained.** from t
19390 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d he xRandomness m
193a0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
193b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
193c0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f s] object..** ^O
193d0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 n all subsequent
193e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 invocations, th
193f0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e e pseudo-randomn
19400 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 ess is generated
19410 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 .** internally a
19420 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 nd without recou
19430 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 rse to the [sqli
19440 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d te3_vfs] xRandom
19450 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a ness.** method..
19460 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
19470 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e randomness(int N
19480 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a , void *P);../*.
19490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
194a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 pile-Time Author
194b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ization Callback
194c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
194d0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
194e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
194f0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
19500 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
19510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19520 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
19530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
19540 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
19550 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
19560 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
19570 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
19580 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
19590 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
195a0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
195b0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
195c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
195d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
195e0 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 pare16()] and [s
195f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
19600 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 _v2()]. ^At var
19610 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
19620 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
19630 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
19640 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
19650 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
19660 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
19670 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
19680 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19690 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
196a0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
196b0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
196c0 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 d. ^The authori
196d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
196e0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
196f0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
19700 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
19710 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
19720 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
19730 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
19740 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
19750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
19760 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
19770 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
19780 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
19790 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
197a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
197b0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
197c0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
197d0 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 ^If the author
197e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
197f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
19800 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
19810 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
19820 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
19830 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
19840 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
19850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
19860 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
19870 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
19880 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
19890 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
198a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
198b0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
198c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
198d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
198e0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
198f0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
19900 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
19910 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 ^When the callba
19920 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
19930 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
19940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
19950 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
19960 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
19970 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
19980 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
19990 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
199a0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
199b0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
199c0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
199d0 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 .**.** ^The fir
199e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
199f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
19a00 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
19a10 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a y of the third.*
19a20 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 * parameter to t
19a30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
19a40 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 uthorizer() inte
19a50 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f rface. ^The seco
19a60 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
19a70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
19a80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
19a90 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
19aa0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
19ab0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
19ac0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
19ad0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
19ae0 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 ed. ^The third t
19af0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
19b00 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 ameters.** to th
19b10 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a e callback are z
19b20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
19b30 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
19b40 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ain additional.*
19b50 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 * details about
19b60 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 the action to be
19b70 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
19b80 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
19b90 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
19ba0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 E_READ].** and t
19bb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
19bc0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f rns [SQLITE_IGNO
19bd0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 RE] then the.**
19be0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
19bf0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 ent] statement i
19c00 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f s constructed to
19c10 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 substitute.** a
19c20 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 NULL value in p
19c30 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c lace of the tabl
19c40 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f e column that wo
19c50 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e uld have.** been
19c60 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 read if [SQLITE
19c70 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 _OK] had been re
19c80 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 turned. The [SQ
19c90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 LITE_IGNORE].**
19ca0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 return can be us
19cb0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e ed to deny an un
19cc0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 trusted user acc
19cd0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 ess to individua
19ce0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 l.** columns of
19cf0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 a table..** ^If
19d00 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
19d10 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 is [SQLITE_DELET
19d20 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 E] and the callb
19d30 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b ack returns.** [
19d40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
19d50 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d hen the [DELETE]
19d60 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 operation proce
19d70 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b eds but the.** [
19d80 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a truncate optimiz
19d90 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c ation] is disabl
19da0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 ed and all rows
19db0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 are deleted indi
19dc0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 vidually..**.**
19dd0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 An authorizer is
19de0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 used when [sqli
19df0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
19e00 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 eparing].** SQL
19e10 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 statements from
19e20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 an untrusted sou
19e30 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 rce, to ensure t
19e40 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 hat the SQL stat
19e50 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 ements.** do not
19e60 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 try to access d
19e70 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 ata they are not
19e80 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c allowed to see,
19e90 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f or that they do
19ea0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 not.** try to e
19eb0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 xecute malicious
19ec0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
19ed0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 damage the data
19ee0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 base. For.** ex
19ef0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
19f00 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 ation may allow
19f10 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 a user to enter
19f20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c arbitrary.** SQL
19f30 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 queries for eva
19f40 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 luation by a dat
19f50 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 abase. But the
19f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
19f70 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 .** not want the
19f80 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 user to be able
19f90 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 to make arbitra
19fa0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ry changes to th
19fb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 e.** database.
19fc0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f An authorizer co
19fd0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 uld then be put
19fe0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 in place while t
19ff0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 he.** user-enter
1a000 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 ed SQL is being
1a010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1a020 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 | prepared] tha
1a030 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 t.** disallows e
1a040 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 verything except
1a050 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1a060 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ents..**.** Appl
1a070 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 ications that ne
1a080 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 ed to process SQ
1a090 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 L from untrusted
1a0a0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 sources.** migh
1a0b0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 t also consider
1a0c0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 lowering resourc
1a0d0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b e limits using [
1a0e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
1a0f0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 .** and limiting
1a100 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 database size u
1a110 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 sing the [max_pa
1a120 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
1a130 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f A].** in additio
1a140 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 n to using an au
1a150 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 thorizer..**.**
1a160 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^(Only a single
1a170 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 authorizer can b
1a180 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 e in place on a
1a190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a1a0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 ion.** at a time
1a1b0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 . Each call to
1a1c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a1d0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 orizer overrides
1a1e0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 the.** previous
1a1f0 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 call.)^ ^Disab
1a200 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 le the authorize
1a210 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 r by installing
1a220 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e a NULL callback.
1a230 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
1a240 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 er is disabled b
1a250 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
1a260 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
1a270 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
1a280 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
1a290 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
1a2a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
1a2b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1a2c0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f nvoked the autho
1a2d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a rizer callback..
1a2e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
1a2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1a300 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
1a310 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
1a320 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
1a330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a340 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
1a350 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
1a360 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
1a370 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 ..**.** ^When [s
1a380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1a390 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 2()] is used to
1a3a0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
1a3b0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 ent, the.** stat
1a3c0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 ement might be r
1a3d0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e e-prepared durin
1a3e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1a3f0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 )] due to a .**
1a400 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 schema change.
1a410 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 Hence, the appli
1a420 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e cation should en
1a430 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a sure that the.**
1a440 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 correct authori
1a450 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d zer callback rem
1a460 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 ains in place du
1a470 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 ring the [sqlite
1a480 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_step()]..**.**
1a490 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
1a4a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1a4b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ack is invoked o
1a4c0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 nly during.** [s
1a4d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1a4e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
1a4f0 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f s. Authorizatio
1a500 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 n is not.** perf
1a510 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 ormed during sta
1a520 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f tement evaluatio
1a530 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 n in [sqlite3_st
1a540 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a ep()], unless.**
1a550 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 as stated in th
1a560 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 e previous parag
1a570 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 raph, sqlite3_st
1a580 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 ep() invokes.**
1a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1a5a0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 v2() to reprepar
1a5b0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 e a statement af
1a5c0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 ter a schema cha
1a5d0 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 nge..*/.int sqli
1a5e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1a5f0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
1a600 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
1a610 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
1a620 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1a630 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
1a640 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
1a650 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
1a660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a670 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
1a680 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 rn Codes.**.** T
1a690 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1a6a0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1a6b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1a6c0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
1a6d0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
1a6e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
1a6f0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
1a700 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
1a710 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
1a720 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
1a730 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
1a740 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
1a750 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
1a760 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1a770 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
1a780 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
1a790 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
1a7a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
1a7b0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
1a7c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 QLITE_IGNORE is
1a7d0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b also used as a [
1a7e0 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 SQLITE_ROLLBACK
1a7f0 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a | return code].*
1a800 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 * from the [sqli
1a810 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 te3_vtab_on_conf
1a820 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 lict()] interfac
1a830 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
1a840 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
1a850 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
1a860 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
1a870 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
1a880 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
1a890 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
1a8a0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
1a8b0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
1a8c0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
1a8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
1a8e0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
1a8f0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
1a900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a910 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
1a920 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
1a930 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1a940 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
1a950 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
1a960 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
1a970 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
1a980 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
1a990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1a9a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
1a9b0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
1a9c0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
1a9d0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
1a9e0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
1a9f0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
1aa00 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
1aa10 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
1aa20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1aa30 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
1aa40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
1aa50 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
1aa60 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
1aa70 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
1aa80 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
1aa90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
1aaa0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
1aab0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
1aac0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
1aad0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
1aae0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
1aaf0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
1ab00 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
1ab10 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
1ab20 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
1ab30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
1ab40 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d ^(The 5th param
1ab50 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
1ab60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1ab70 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
1ab80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
1ab90 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
1aba0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
1abb0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 icable.)^ ^The
1abc0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
1abd0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1abe0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
1abf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
1ac00 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
1ac10 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
1ac20 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1ac30 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
1ac40 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
1ac50 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
1ac60 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
1ac70 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
1ac80 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
1ac90 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
1aca0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1acb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 ************** 3
1acc0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 rd ************
1acd0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 4th ***********/
1ace0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1acf0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 CREATE_INDEX
1ad00 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 1 /* Ind
1ad10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1ad20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1ad30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1ad40 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 REATE_TABLE
1ad50 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 2 /* Tabl
1ad60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1ad70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1ad80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1ad90 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 EATE_TEMP_INDEX
1ada0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 3 /* Index
1adb0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1adc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1add0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1ade0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ATE_TEMP_TABLE
1adf0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4 /* Table
1ae00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1ae10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1ae20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1ae30 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 TE_TEMP_TRIGGER
1ae40 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 5 /* Trigger
1ae50 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1ae60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1ae70 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1ae80 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 E_TEMP_VIEW
1ae90 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 6 /* View Nam
1aea0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1aeb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1aec0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1aed0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1aee0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 7 /* Trigger N
1aef0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1af00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1af10 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1af20 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 VIEW 8
1af30 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1af40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1af50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1af60 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 SQLITE_DELETE
1af70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 9
1af80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1af90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1afa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1afb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 SQLITE_DROP_INDE
1afc0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 X 10
1afd0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1afe0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1aff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b000 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 QLITE_DROP_TABLE
1b010 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 11
1b020 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1b030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1b040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b050 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 LITE_DROP_TEMP_I
1b060 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f NDEX 12 /
1b070 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1b080 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1b090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b0a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 ITE_DROP_TEMP_TA
1b0b0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a BLE 13 /*
1b0c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b0d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b0e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b0f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 TE_DROP_TEMP_TRI
1b100 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 GGER 14 /*
1b110 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1b120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b140 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 E_DROP_TEMP_VIEW
1b150 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 15 /* V
1b160 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1b170 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1b180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b190 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 _DROP_TRIGGER
1b1a0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 16 /* Tr
1b1b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1b1c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1b1d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b1e0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 DROP_VIEW
1b1f0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 17 /* Vie
1b200 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1b210 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1b220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1b230 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 NSERT
1b240 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 18 /* Tabl
1b250 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1b260 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1b270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
1b280 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
1b290 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 19 /* Pragm
1b2a0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 a Name 1st a
1b2b0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 rg or NULL */.#d
1b2c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
1b2d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
1b2e0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 20 /* Table
1b2f0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
1b300 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1b310 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 fine SQLITE_SELE
1b320 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CT
1b330 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 21 /* NULL
1b340 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 NULL
1b350 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b360 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
1b370 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 ACTION
1b380 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 22 /* Operatio
1b390 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 n NULL
1b3a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1b3b0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 ne SQLITE_UPDATE
1b3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
1b3d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
1b3e0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
1b3f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1b400 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 e SQLITE_ATTACH
1b410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 24
1b420 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 /* Filename
1b430 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1b440 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b450 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 SQLITE_DETACH
1b460 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 25
1b470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
1b480 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 me NULL
1b490 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b4a0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 SQLITE_ALTER_TAB
1b4b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 LE 26
1b4c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
1b4d0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 e Table Name
1b4e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b4f0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 QLITE_REINDEX
1b500 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 27
1b510 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1b520 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1b530 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1b540 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 LITE_ANALYZE
1b550 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 28 /
1b560 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1b570 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b580 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b590 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c ITE_CREATE_VTABL
1b5a0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a E 29 /*
1b5b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b5c0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
1b5d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b5e0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 TE_DROP_VTABLE
1b5f0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 30 /*
1b600 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1b610 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
1b620 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b630 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 E_FUNCTION
1b640 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 31 /* N
1b650 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 ULL F
1b660 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a unction Name *
1b670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b680 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 _SAVEPOINT
1b690 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 32 /* Op
1b6a0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 eration Sa
1b6b0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f vepoint Name */
1b6c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b6d0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 COPY
1b6e0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 0 /* No
1b6f0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a longer used */..
1b700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b710 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
1b720 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
1b730 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1b740 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 ines register ca
1b750 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 llback functions
1b760 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 that can be use
1b770 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 d for.** tracing
1b780 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 and profiling t
1b790 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
1b7a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
1b7b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
1b7c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1b7d0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
1b7e0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e e3_trace() is in
1b7f0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 voked at.** vari
1b800 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 ous times when a
1b810 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
1b820 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 is being run by
1b830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b840 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
1b850 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
1b860 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
1b870 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 th a UTF-8 rende
1b880 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 ring of the.** S
1b890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
1b8a0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 t as the stateme
1b8b0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
1b8c0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 executing..** ^(
1b8d0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 Additional sqlit
1b8e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
1b8f0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 acks might occur
1b900 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
1b910 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
1b920 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
1b930 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
1b940 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
1b950 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
1b960 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
1b970 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
1b980 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ger.)^.**.** ^Th
1b990 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1b9a0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1b9b0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
1b9c0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
1b9d0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
1b9e0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
1b9f0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
1ba00 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
1ba10 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
1ba20 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
1ba30 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
1ba40 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
1ba50 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
1ba60 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
1ba70 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
1ba80 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
1ba90 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
1baa0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
1bab0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
1bac0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
1bad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
1bae0 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
1baf0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
1bb00 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
1bb10 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
1bb20 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
1bb30 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
1bb40 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
1bb50 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1bb60 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
1bb70 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
1bb80 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
1bb90 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
1bba0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
1bbb0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
1bbc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
1bbd0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
1bbe0 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
1bbf0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1bc00 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
1bc10 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
1bc20 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
1bc30 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
1bc40 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
1bc50 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
1bc60 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
1bc70 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
1bc80 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 id *sqlite3_prof
1bc90 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 ile(sqlite3*,.
1bca0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 void(*xProfile)
1bcb0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1bcc0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
1bcd0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 4), void*);../*.
1bce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
1bcf0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
1bd00 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
1bd10 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
1bd20 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c s_handler(D,N,X,
1bd30 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 P) interface cau
1bd40 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ses the callback
1bd50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 .** function X t
1bd60 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 o be invoked per
1bd70 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 iodically during
1bd80 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 long running ca
1bd90 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
1bda0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c e3_exec()], [sql
1bdb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 ite3_step()] and
1bdc0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1bdd0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 ble()] for.** da
1bde0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1bdf0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 n D. An example
1be00 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a use for this.**
1be10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f interface is to
1be20 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 keep a GUI upda
1be30 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 ted during a lar
1be40 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 ge query..**.**
1be50 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 ^The parameter P
1be60 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 is passed throu
1be70 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 gh as the only p
1be80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1be90 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
1bea0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 ction X. ^The p
1beb0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 arameter N is th
1bec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
1bed0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
1bee0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
1bef0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
1bf00 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
1bf10 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
1bf20 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
1bf30 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e ack X..**.** ^On
1bf40 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
1bf50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
1bf60 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
1bf70 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
1bf80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1bf90 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
1bfa0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
1bfb0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
1bfc0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
1bfd0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
1bfe0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
1bff0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
1c000 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
1c010 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1c020 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
1c030 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
1c040 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
1c050 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
1c060 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
1c070 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
1c080 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1c090 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
1c0a0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
1c0b0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
1c0c0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
1c0d0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
1c0e0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
1c0f0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
1c100 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
1c110 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1c120 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
1c130 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
1c140 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
1c150 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
1c160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1c170 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
1c180 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
1c190 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c1b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
1c1c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
1c1d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
1c1e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c1f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
1c200 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
1c210 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
1c220 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 h..**.*/.void sq
1c230 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
1c240 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
1c250 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
1c260 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
1c270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
1c280 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
1c290 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
1c2a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
1c2b0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 tines open an SQ
1c2c0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 Lite database fi
1c2d0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 le as specified
1c2e0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e by the .** filen
1c2f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
1c300 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
1c310 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
1c320 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
1c330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1c340 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
1c350 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
1c360 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
1c370 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
1c380 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
1c390 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
1c3a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c3b0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
1c3c0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
1c3d0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
1c3e0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
1c3f0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
1c400 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
1c410 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
1c420 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1c430 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
1c440 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
1c450 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
1c460 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
1c470 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
1c480 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
1c490 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
1c4a0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
1c4b0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
1c4c0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
1c4d0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
1c4e0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
1c4f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
1c500 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
1c510 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
1c520 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
1c530 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
1c540 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1c550 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
1c560 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
1c570 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
1c580 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
1c590 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
1c5a0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
1c5b0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
1c5c0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
1c5d0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
1c5e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
1c5f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
1c600 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
1c610 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
1c620 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
1c630 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f if.** sqlite3_o
1c640 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
1c650 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 _open_v2() is ca
1c660 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
1c670 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
1c680 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 byte order if s
1c690 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 qlite3_open16()
1c6a0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
1c6b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
1c6c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
1c6d0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
1c6e0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 resources.** as
1c6f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
1c700 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
1c710 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 ection] handle s
1c720 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
1c730 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 d by.** passing
1c740 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
1c750 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 lose()] when it
1c760 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 is no longer req
1c770 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
1c780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1c790 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 () interface wor
1c7a0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
1c7b0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 open().** except
1c7c0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 that it accepts
1c7d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
1c7e0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 parameters for a
1c7f0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f dditional contro
1c800 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 l.** over the ne
1c810 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
1c820 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c ction. ^(The fl
1c830 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
1c840 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1c850 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f _v2() can take o
1c860 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c ne of.** the fol
1c870 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c lowing three val
1c880 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 ues, optionally
1c890 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 combined with th
1c8a0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 e .** [SQLITE_OP
1c8b0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
1c8c0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
1c8d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
1c8e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c EN_SHAREDCACHE],
1c8f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 .** and/or [SQLI
1c900 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1c910 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a ACHE] flags:)^.*
1c920 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
1c930 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1c940 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
1c950 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1c960 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
1c970 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
1c980 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1c990 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
1c9a0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
1c9b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1c9c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1c9d0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
1c9e0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
1c9f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1ca00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1ca10 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1ca20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
1ca30 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
1ca40 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
1ca50 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
1ca60 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
1ca70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
1ca80 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
1ca90 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1caa0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
1cab0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
1cac0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1cad0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
1cae0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
1caf0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
1cb00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
1cb10 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
1cb20 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1cb30 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1cb40 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1cb50 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 , and is created
1cb60 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
1cb70 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
1cb80 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
1cb90 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
1cba0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
1cbb0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1cbc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1cbd0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a n16().</dd>)^.**
1cbe0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
1cbf0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
1cc00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
1cc10 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
1cc20 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
1cc30 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
1cc40 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 bove or one of t
1cc50 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 he combinations
1cc60 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 shown above comb
1cc70 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ined.** with the
1cc80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
1cc90 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
1cca0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c OPEN_FULLMUTEX],
1ccb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1ccc0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e _SHAREDCACHE] an
1ccd0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 d/or [SQLITE_OPE
1cce0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
1ccf0 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 flags,.** then t
1cd00 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
1cd10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
1cd20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
1cd30 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
1cd40 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
1cd50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1cd60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
1cd70 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
1cd80 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
1cd90 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
1cda0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
1cdb0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
1cdc0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
1cdd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
1cde0 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
1cdf0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
1ce00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
1ce10 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
1ce20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1ce30 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
1ce40 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
1ce50 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
1ce60 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
1ce70 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
1ce80 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
1ce90 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
1cea0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
1ceb0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
1cec0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
1ced0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
1cee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1cef0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
1cf00 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
1cf10 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
1cf20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
1cf30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
1cf40 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
1cf50 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
1cf60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
1cf70 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
1cf80 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
1cf90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
1cfa0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
1cfb0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
1cfc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
1cfd0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
1cfe0 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
1cff0 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
1d000 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
1d010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
1d020 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
1d030 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1d040 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
1d050 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
1d060 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
1d070 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
1d080 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
1d090 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
1d0a0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
1d0b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
1d0c0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
1d0d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1d0e0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
1d0f0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
1d100 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1d110 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
1d120 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
1d130 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
1d140 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
1d150 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
1d160 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
1d170 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
1d180 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
1d190 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
1d1a0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
1d1b0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
1d1c0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
1d1d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d1e0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
1d1f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1d200 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1d210 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
1d220 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
1d230 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
1d240 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
1d250 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
1d260 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
1d270 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
1d280 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
1d290 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
1d2a0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
1d2b0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
1d2c0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
1d2d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
1d2e0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
1d2f0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
1d300 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
1d310 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
1d320 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
1d330 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
1d340 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
1d350 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
1d360 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1d370 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
1d380 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
1d390 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
1d3a0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
1d3b0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
1d3c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1d3d0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
1d3e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 55 52 49 20 66 .**.** ^If URI f
1d3f0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
1d400 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
1d410 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e d, and the filen
1d420 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
1d430 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c begins with "fil
1d440 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 e:", then the fi
1d450 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 lename is interp
1d460 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 reted as a URI.
1d470 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ^URI.** filename
1d480 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
1d490 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
1d4a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
1d4b0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 69 RI] flag is.** i
1d4c0 73 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 s set in the fou
1d4d0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
1d4e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1d4f0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
1d500 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
1d510 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
1d520 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
1d530 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
1d540 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
1d550 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
1d560 68 6f 64 2e 20 0a 2a 2a 0a 2a 2a 20 55 52 49 20 hod. .**.** URI
1d570 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 filenames are pa
1d580 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 rsed according t
1d590 6f 20 52 46 43 20 31 37 33 38 2e 20 49 66 20 74 o RFC 1738. If t
1d5a0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 he URI contains
1d5b0 61 6e 0a 2a 2a 20 27 61 75 74 68 6f 72 69 74 79 an.** 'authority
1d5c0 27 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 ', then it must
1d5d0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 be either an emp
1d5e0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 ty string or the
1d5f0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 string .** "loc
1d600 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 alhost". ^If the
1d610 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f authority is no
1d620 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e t an empty strin
1d630 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 g or "localhost"
1d640 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 , an .** error i
1d650 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
1d660 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 27 e caller. ^The '
1d670 66 72 61 67 6d 65 6e 74 27 20 63 6f 6d 70 6f 6e fragment' compon
1d680 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 ent of a URI, if
1d690 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 .** present, is
1d6a0 20 61 6c 77 61 79 73 20 69 67 6e 6f 72 65 64 2e always ignored.
1d6b0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
1d6c0 73 65 73 20 74 68 65 20 27 70 61 74 68 27 20 63 ses the 'path' c
1d6d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 omponent of the
1d6e0 55 52 49 20 61 73 20 74 68 65 20 70 61 74 68 20 URI as the path
1d6f0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
1d700 66 69 6c 65 0a 2a 2a 20 74 6f 20 6f 70 65 6e 2e file.** to open.
1d710 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 ^If the path be
1d720 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 gins with a '/'
1d730 63 68 61 72 61 63 74 65 72 2c 20 74 68 65 6e 20 character, then
1d740 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 it is interprete
1d750 64 20 61 73 0a 2a 2a 20 61 6e 20 61 62 73 6f 6c d as.** an absol
1d760 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 69 74 ute path. ^If it
1d770 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
1d780 77 69 74 68 20 61 20 27 2f 27 2c 20 69 74 20 69 with a '/', it i
1d790 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
1d7a0 20 61 20 0a 2a 2a 20 72 65 6c 61 74 69 76 65 20 a .** relative
1d7b0 70 61 74 68 2e 20 5e 4f 6e 20 77 69 6e 64 6f 77 path. ^On window
1d7c0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d s, the first com
1d7d0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 ponent of an abs
1d7e0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 olute path .** i
1d7f0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 s a drive specif
1d800 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 ication (e.g. "C
1d810 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 71 :")..**.** The q
1d820 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
1d830 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 f a URI may cont
1d840 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 ain parameters t
1d850 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 hat are interpre
1d860 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 ted.** either by
1d870 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 SQLite itself,
1d880 6f 72 20 62 79 20 61 20 5b 73 71 6c 69 74 65 33 or by a [sqlite3
1d890 5f 76 66 73 20 7c 20 63 75 73 74 6f 6d 20 56 46 _vfs | custom VF
1d8a0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
1d8b0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 ]..** SQLite int
1d8c0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c erprets the foll
1d8d0 6f 77 69 6e 67 20 66 6f 75 72 20 71 75 65 72 79 owing four query
1d8e0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a parameters:.**.
1d8f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
1d900 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 > <b>vfs</b>: ^T
1d910 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 he "vfs" paramet
1d920 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 er may be used t
1d930 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 o specify the na
1d940 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 me of.** a V
1d950 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 FS object that p
1d960 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 rovides the oper
1d970 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
1d980 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 erface that shou
1d990 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 ld.** be use
1d9a0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 d to access the
1d9b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e database file on
1d9c0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 disk. ^If this
1d9d0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
1d9e0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 .** an empty
1d9f0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 string the defa
1da00 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 ult VFS object i
1da10 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 s used. ^Specify
1da20 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a ing an unknown.*
1da30 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 * VFS is an
1da40 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 error. ^If sqlit
1da50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
1da60 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 used and the vfs
1da70 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
1da80 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 present, then
1da90 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 the VFS specifie
1daa0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 d by the option
1dab0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 takes precedence
1dac0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 over.** the
1dad0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
1dae0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
1daf0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1db00 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
1db10 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 * <li> <b>mode
1db20 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 </b>: ^(The mode
1db30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
1db40 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
1db50 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a "ro", "rw" or.**
1db60 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 "rwc". Atte
1db70 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
1db80 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
1db90 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 lue is an error)
1dba0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 ^. .** ^If "
1dbb0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 ro" is specified
1dbc0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
1dbd0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
1dbe0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 r read-only .**
1dbf0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 access, just
1dc00 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 as if the [SQLI
1dc10 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
1dc20 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 ] flag had been
1dc30 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 set in the .**
1dc40 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e third argumen
1dc50 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 t to sqlite3_pre
1dc60 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 pare_v2(). ^If t
1dc70 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
1dc80 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 s set to .**
1dc90 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 "rw", then the
1dca0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1dcb0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 ed for read-writ
1dcc0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 e (but not creat
1dcd0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 e) .** acces
1dce0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f s, as if SQLITE_
1dcf0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 OPEN_READWRITE (
1dd00 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f but not SQLITE_O
1dd10 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 PEN_CREATE) had
1dd20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 .** been set
1dd30 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 . ^Value "rwc" i
1dd40 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
1dd50 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a setting both .**
1dd60 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
1dd70 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 _READWRITE and S
1dd80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1dd90 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f E. ^If sqlite3_o
1dda0 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 pen_v2() is .**
1ddb0 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 used, it is
1ddc0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 an error to spec
1ddd0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 ify a value for
1dde0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
1ddf0 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 er that is .**
1de00 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 less restrict
1de10 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 ive than that sp
1de20 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
1de30 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74 lags passed as t
1de40 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 he third .**
1de50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1de60 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
1de70 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
1de80 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
1de90 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
1dea0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
1deb0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
1dec0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
1ded0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
1dee0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
1def0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
1df00 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
1df10 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
1df20 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
1df30 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
1df40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
1df50 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
1df60 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
1df70 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
1df80 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
1df90 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
1dfa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
1dfb0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
1dfc0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
1dfd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
1dfe0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
1dff0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
1e000 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
1e010 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
1e020 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
1e030 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
1e040 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 our requested by
1e050 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 setting.**
1e060 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
1e070 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 ATECACHE or SQLI
1e080 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
1e090 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 CHE flag..**.**
1e0a0 20 20 3c 6c 69 3e 20 3c 62 3e 72 65 61 64 6f 6e <li> <b>readon
1e0b0 6c 79 5f 73 68 6d 3c 2f 62 3e 3a 20 5e 54 68 65 ly_shm</b>: ^The
1e0c0 20 72 65 61 64 6f 6e 6c 79 5f 73 68 6d 20 70 61 readonly_shm pa
1e0d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
1e0e0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 65 69 et to .** ei
1e0f0 74 68 65 72 20 22 31 22 20 6f 72 20 22 30 22 2e ther "1" or "0".
1e100 20 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 Setting it to "
1e110 31 22 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 1" indicates tha
1e120 74 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 t if the databas
1e130 65 0a 2a 2a 20 20 20 20 20 69 73 20 69 6e 20 57 e.** is in W
1e140 41 4c 20 6d 6f 64 65 20 61 6e 64 20 72 65 61 64 AL mode and read
1e150 2d 77 72 69 74 65 20 61 63 63 65 73 73 20 74 6f -write access to
1e160 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
1e170 73 68 61 72 65 64 20 0a 2a 2a 20 20 20 20 20 6d shared .** m
1e180 65 6d 6f 72 79 20 72 65 67 69 6f 6e 20 63 61 6e emory region can
1e190 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 64 2c not be obtained,
1e1a0 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 then an attempt
1e1b0 20 73 68 6f 75 6c 64 20 62 65 20 6d 61 64 65 20 should be made
1e1c0 74 6f 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 74 to open.** t
1e1d0 68 65 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 he shared-memory
1e1e0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
1e1f0 64 65 20 69 6e 73 74 65 61 64 2e 20 49 66 20 74 de instead. If t
1e200 68 65 72 65 20 65 78 69 73 74 20 6f 6e 65 20 6f here exist one o
1e210 72 0a 2a 2a 20 20 20 20 20 6d 6f 72 65 20 6f 74 r.** more ot
1e220 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6c 69 her database cli
1e230 65 6e 74 73 20 74 68 61 74 20 68 61 76 65 20 72 ents that have r
1e240 65 61 64 2d 77 72 69 74 65 20 63 6f 6e 6e 65 63 ead-write connec
1e250 74 69 6f 6e 73 20 74 6f 20 74 68 65 0a 2a 2a 20 tions to the.**
1e260 20 20 20 20 64 61 74 61 62 61 73 65 20 73 68 61 database sha
1e270 72 65 64 2d 6d 65 6d 6f 72 79 2c 20 74 68 65 6e red-memory, then
1e280 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 73 68 61 a read-only sha
1e290 72 65 64 2d 6d 65 6d 6f 72 79 20 63 6f 6e 6e 65 red-memory conne
1e2a0 63 74 69 6f 6e 20 77 6f 72 6b 73 20 0a 2a 2a 20 ction works .**
1e2b0 20 20 20 20 66 69 6e 65 2e 20 48 6f 77 65 76 65 fine. Howeve
1e2c0 72 2c 20 69 66 20 74 68 65 72 65 20 65 78 69 73 r, if there exis
1e2d0 74 20 6e 6f 20 63 6c 69 65 6e 74 73 20 77 69 74 t no clients wit
1e2e0 68 20 72 65 61 64 2d 77 72 69 74 65 20 63 6f 6e h read-write con
1e2f0 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 20 20 20 nections .**
1e300 20 74 6f 20 74 68 65 20 73 68 61 72 65 64 2d 6d to the shared-m
1e310 65 6d 6f 72 79 20 61 6e 64 20 74 68 65 20 6d 6f emory and the mo
1e320 73 74 20 72 65 63 65 6e 74 20 73 75 63 68 20 63 st recent such c
1e330 72 61 73 68 65 64 20 6f 72 20 77 61 73 20 69 6e rashed or was in
1e340 74 65 72 72 75 70 74 65 64 0a 2a 2a 20 20 20 20 terrupted.**
1e350 20 62 79 20 61 20 70 6f 77 65 72 20 66 61 69 6c by a power fail
1e360 75 72 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ure, then it is
1e370 70 6f 73 73 69 62 6c 65 20 66 6f 72 20 61 20 64 possible for a d
1e380 61 74 61 62 61 73 65 20 63 6c 69 65 6e 74 20 75 atabase client u
1e390 73 69 6e 67 20 61 0a 2a 2a 20 20 20 20 20 72 65 sing a.** re
1e3a0 61 64 2d 6f 6e 6c 79 20 63 6f 6e 6e 65 63 74 69 ad-only connecti
1e3b0 6f 6e 20 74 6f 20 72 65 74 75 72 6e 20 69 6e 63 on to return inc
1e3c0 6f 72 72 65 63 74 20 64 61 74 61 2c 20 69 6e 63 orrect data, inc
1e3d0 6f 72 72 65 63 74 6c 79 20 72 65 70 6f 72 74 20 orrectly report
1e3e0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 .** database
1e3f0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 6f 72 20 corruption, or
1e400 72 65 74 75 72 6e 20 61 6e 20 53 51 4c 49 54 45 return an SQLITE
1e410 5f 52 45 41 44 4f 4e 4c 59 20 65 72 72 6f 72 2e _READONLY error.
1e420 20 4f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 Or if the.**
1e430 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 most recent re
1e440 61 64 2d 77 72 69 74 65 20 63 6f 6e 6e 65 63 74 ad-write connect
1e450 69 6f 6e 20 73 68 75 74 20 64 6f 77 6e 20 63 6c ion shut down cl
1e460 65 61 6e 6c 79 2c 20 69 74 20 6d 61 79 20 6e 6f eanly, it may no
1e470 74 20 62 65 0a 2a 2a 20 20 20 20 20 70 6f 73 73 t be.** poss
1e480 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 ible to open the
1e490 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 69 shared-memory i
1e4a0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
1e4b0 20 61 74 20 61 6c 6c 2c 20 61 6e 64 20 53 51 4c at all, and SQL
1e4c0 69 74 65 0a 2a 2a 20 20 20 20 20 77 69 6c 6c 20 ite.** will
1e4d0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 43 41 return SQLITE_CA
1e4e0 4e 54 4f 50 45 4e 2e 0a 2a 2a 20 3c 2f 75 6c 3e NTOPEN..** </ul>
1e4f0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
1e500 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
1e510 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
1e520 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
1e530 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
1e540 6e 0a 2a 2a 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a n.** error..**.*
1e550 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 * URI filename e
1e560 78 61 6d 70 6c 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c xamples:.**.** <
1e570 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
1e580 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 align=center ce
1e590 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 llpadding=5>.**
1e5a0 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c <tr><th> URI fil
1e5b0 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 enames <th> Resu
1e5c0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 lts.** <tr><td>
1e5d0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 file:data.db <td
1e5e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
1e5f0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 pen the file "da
1e600 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
1e610 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e rrent directory.
1e620 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
1e630 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 e:/home/fred/dat
1e640 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 a.db<br>.**
1e650 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d file:///hom
1e660 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
1e670 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 br> .**
1e680 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 file://localhos
1e690 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 t/home/fred/data
1e6a0 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a .db <br> <td> .*
1e6b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
1e6c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
1e6d0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 e "/home/fred/da
1e6e0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c ta.db"..** <tr><
1e6f0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 td> file://darks
1e700 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 tar/home/fred/da
1e710 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 ta.db <td> .**
1e720 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 An error
1e730 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 . "darkstar" is
1e740 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 not a recognized
1e750 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c authority..** <
1e760 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 tr><td style="wh
1e770 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 ite-space:nowrap
1e780 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 "> .**
1e790 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d file:///C:/Docum
1e7a0 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 ents%20and%20Set
1e7b0 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 tings/fred/Deskt
1e7c0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 op/data.db.**
1e7d0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f <td> Windows o
1e7e0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 nly: Open the fi
1e7f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 le "data.db" on
1e800 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f fred's desktop o
1e810 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 n drive.**
1e820 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 C:. Note tha
1e830 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 t the %20 escapi
1e840 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 ng in this examp
1e850 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 le is not strict
1e860 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ly .**
1e870 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 necessary - spac
1e880 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e e characters can
1e890 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c be used literal
1e8a0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ly.** i
1e8b0 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e n URI filenames.
1e8c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
1e8d0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
1e8e0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 o&cache=private
1e8f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
1e900 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 Open file "dat
1e910 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
1e920 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 rent directory f
1e930 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 or read-only acc
1e940 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 ess..**
1e950 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 Regardless of w
1e960 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
1e970 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 ared-cache mode
1e980 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a is enabled by.**
1e990 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c defaul
1e9a0 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 t, use a private
1e9b0 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c cache..** <tr><
1e9c0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 td> file:/home/f
1e9d0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d red/data.db?vfs=
1e9e0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e unix-nolock <td>
1e9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
1ea00 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 n file "/home/fr
1ea10 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 ed/data.db". Use
1ea20 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 the special VFS
1ea30 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a "unix-nolock"..
1ea40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
1ea50 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 :data.db?mode=re
1ea60 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 adonly <td> .**
1ea70 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
1ea80 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 r. "readonly" is
1ea90 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 not a valid opt
1eaa0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 ion for the "mod
1eab0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a e" parameter..**
1eac0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 </table>.**.**
1ead0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c ^URI hexadecimal
1eae0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
1eaf0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 s (%HH) are supp
1eb00 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 orted within the
1eb10 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 path and.** que
1eb20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
1eb30 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 a URI. A hexade
1eb40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
1eb50 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f uence consists o
1eb60 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 f a.** percent s
1eb70 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c ign - "%" - foll
1eb80 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 owed by exactly
1eb90 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 two hexadecimal
1eba0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 digits .** speci
1ebb0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 fying an octet v
1ebc0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 alue. ^Before th
1ebd0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 e path or query
1ebe0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a components of a.
1ebf0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 ** URI filename
1ec00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c are interpreted,
1ec10 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 they are encode
1ec20 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e d using UTF-8 an
1ec30 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 d all .** hexade
1ec40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
1ec50 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 uences replaced
1ec60 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 by a single byte
1ec70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
1ec80 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ** corresponding
1ec90 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 octet. If this
1eca0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 process generate
1ecb0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 s an invalid UTF
1ecc0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 -8 encoding,.**
1ecd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
1ece0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
1ecf0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
1ed00 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
1ed10 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
1ed20 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
1ed30 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
1ed40 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
1ed50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1ed60 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
1ed70 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
1ed80 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
1ed90 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
1eda0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
1edb0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
1edc0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
1edd0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
1ede0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
1edf0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
1ee00 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
1ee10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
1ee20 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
1ee30 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 2()..*/.int sqli
1ee40 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
1ee50 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
1ee60 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
1ee70 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
1ee80 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
1ee90 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
1eea0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
1eeb0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
1eec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
1eed0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
1eee0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
1eef0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
1ef00 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
1ef10 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
1ef20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
1ef30 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
1ef40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
1ef50 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
1ef60 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
1ef70 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
1ef80 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
1ef90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
1efa0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
1efb0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
1efc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
1efd0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
1efe0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
1eff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
1f000 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
1f010 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
1f020 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
1f030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
1f040 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
1f050 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 ssages.**.** ^Th
1f060 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 e sqlite3_errcod
1f070 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 e() interface re
1f080 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 turns the numeri
1f090 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 c [result code]
1f0a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
1f0b0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 result code] for
1f0c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1f0d0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f failed sqlite3_
1f0e0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 * API call.** as
1f0f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
1f100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f110 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f tion]. If a prio
1f120 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 r API call faile
1f130 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 d.** but the mos
1f140 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c t recent API cal
1f150 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 l succeeded, the
1f160 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
1f170 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 om.** sqlite3_er
1f180 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 rcode() is undef
1f190 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 ined. ^The sqli
1f1a0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
1f1b0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
1f1c0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
1f1d0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
1f1e0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
1f1f0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
1f200 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
1f210 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
1f220 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
1f230 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
1f240 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f250 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
1f260 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1f270 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
1f280 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
1f290 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
1f2a0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
1f2b0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
1f2c0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
1f2d0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 y..** ^(Memory t
1f2e0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
1f2f0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
1f300 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
1f310 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
1f320 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
1f330 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
1f340 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
1f350 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
1f360 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
1f370 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
1f380 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
1f390 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
1f3a0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
1f3b0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
1f3c0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
1f3d0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ctions.)^.**.**
1f3e0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 When the seriali
1f3f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
1f400 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 ode] is in use,
1f410 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a it might be the.
1f420 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 ** case that a s
1f430 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 econd error occu
1f440 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 rs on a separate
1f450 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 thread in betwe
1f460 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f en.** the time o
1f470 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f f the first erro
1f480 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 r and the call t
1f490 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 o these interfac
1f4a0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 es..** When that
1f4b0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 happens, the se
1f4c0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 cond error will
1f4d0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 be reported sinc
1f4e0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 e these.** inter
1f4f0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 faces always rep
1f500 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ort the most rec
1f510 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 ent result. To
1f520 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 avoid.** this, e
1f530 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f ach thread can o
1f540 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 btain exclusive
1f550 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 use of the [data
1f560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1f570 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e D.** by invokin
1f580 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
1f590 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 _enter]([sqlite3
1f5a0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 _db_mutex](D)) b
1f5b0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a efore beginning.
1f5c0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 ** to use D and
1f5d0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 invoking [sqlite
1f5e0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 3_mutex_leave]([
1f5f0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
1f600 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 ](D)) after.** a
1f610 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ll calls to the
1f620 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 interfaces liste
1f630 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c d here are compl
1f640 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 eted..**.** If a
1f650 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c n interface fail
1f660 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 s with SQLITE_MI
1f670 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 SUSE, that means
1f680 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a the interface.*
1f690 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e * was invoked in
1f6a0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 correctly by the
1f6b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 application. I
1f6c0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 n that case, the
1f6d0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 .** error code a
1f6e0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f nd message may o
1f6f0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 r may not be set
1f700 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1f710 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
1f720 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 *db);.int sqlit
1f730 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
1f740 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
1f750 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
1f760 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
1f770 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f ite3*);.const vo
1f780 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d id *sqlite3_errm
1f790 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a sg16(sqlite3*);.
1f7a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f7b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
1f7c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
1f7d0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
1f7e0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
1f7f0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
1f800 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
1f810 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
1f820 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
1f830 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
1f840 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
1f850 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
1f860 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
1f870 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
1f880 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
1f890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
1f8a0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
1f8b0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
1f8c0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
1f8d0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
1f8e0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
1f8f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
1f900 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
1f910 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
1f920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
1f930 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
1f940 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
1f950 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
1f960 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
1f970 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
1f980 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
1f990 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
1f9a0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
1f9b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
1f9c0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
1f9d0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1f9e0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
1f9f0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
1fa00 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
1fa10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
1fa20 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
1fa30 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
1fa40 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
1fa50 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
1fa60 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
1fa70 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
1fa80 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
1fa90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
1faa0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
1fab0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
1fac0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
1fad0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
1fae0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
1faf0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
1fb00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
1fb10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
1fb20 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
1fb30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
1fb40 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
1fb50 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
1fb60 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
1fb70 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
1fb80 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
1fb90 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
1fba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
1fbb0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
1fbc0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
1fbd0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
1fbe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1fbf0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
1fc00 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
1fc10 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
1fc20 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
1fc30 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
1fc40 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
1fc50 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
1fc60 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
1fc70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
1fc80 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
1fc90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
1fca0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
1fcb0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
1fcc0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
1fcd0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
1fce0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
1fcf0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
1fd00 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
1fd10 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
1fd20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
1fd30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
1fd40 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
1fd50 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
1fd60 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
1fd70 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
1fd80 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
1fd90 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
1fda0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
1fdb0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
1fdc0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
1fdd0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
1fde0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
1fdf0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
1fe00 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
1fe10 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
1fe20 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
1fe30 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
1fe40 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
1fe50 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
1fe60 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
1fe70 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
1fe80 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
1fe90 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
1fea0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
1feb0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
1fec0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
1fed0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
1fee0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
1fef0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
1ff00 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
1ff10 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
1ff20 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
1ff30 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
1ff40 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
1ff50 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
1ff60 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
1ff70 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
1ff80 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
1ff90 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
1ffa0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
1ffb0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
1ffc0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
1ffd0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
1ffe0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
1fff0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
20000 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
20010 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
20020 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
20030 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
20040 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
20050 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
20060 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
20070 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
20080 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
20090 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
200a0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
200b0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
200c0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
200d0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
200e0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
200f0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
20100 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
20110 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
20120 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
20130 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
20140 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
20150 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
20160 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
20170 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
20180 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
20190 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
201a0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
201b0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
201c0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
201d0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
201e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
201f0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
20200 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
20210 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
20220 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
20230 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
20240 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
20250 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
20260 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
20270 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
20280 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
20290 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
202a0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
202b0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
202c0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
202d0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
202e0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
202f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
20300 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
20310 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
20320 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
20330 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
20340 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
20350 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
20360 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
20370 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
20380 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
20390 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
203a0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
203b0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
203c0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
203d0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
203e0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
203f0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
20400 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
20410 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
20420 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
20430 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
20440 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
20450 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
20460 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
20470 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
20480 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c dl>.** ^(<dt>SQL
20490 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
204a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
204b0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
204c0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 any string or B
204d0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 LOB or table row
204e0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 , in bytes.<dd>)
204f0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
20500 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
20510 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
20520 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
20530 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
20540 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
20550 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
20560 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
20570 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a MIT_COLUMN</dt>.
20580 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20590 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
205a0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 umns in a table
205b0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e definition or in
205c0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 the.** result s
205d0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d et of a [SELECT]
205e0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 or the maximum
205f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
20600 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a s in an index.**
20610 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 or in an ORDER
20620 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 BY or GROUP BY c
20630 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a lause.</dd>)^.**
20640 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
20650 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
20660 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
20670 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
20680 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 of the parse tre
20690 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 e on any express
206a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
206b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
206c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
206d0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LECT</dt>.** <dd
206e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
206f0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
20700 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 a compound SELEC
20710 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 T statement.</dd
20720 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
20730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
20740 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 E_OP</dt>.** <dd
20750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
20760 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 ber of instructi
20770 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c ons in a virtual
20780 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d machine program
20790 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c .** used to impl
207a0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 ement an SQL sta
207b0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 tement. This li
207c0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 mit is not curre
207d0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 ntly.** enforced
207e0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 , though that mi
207f0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 ght be added in
20800 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 some future rele
20810 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 ase of.** SQLite
20820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
20830 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
20840 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
20850 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
20860 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
20870 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
20880 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
20890 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
208a0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
208b0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
208c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
208d0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 r of [ATTACH | a
208e0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
208f0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a s].)^</dd>.**.**
20900 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
20910 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
20920 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
20930 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
20940 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 length of the pa
20950 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 ttern argument t
20960 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a o the [LIKE] or.
20970 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 ** [GLOB] operat
20980 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ors.</dd>)^.**.*
20990 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
209a0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
209b0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 MBER</dt>.** <dd
209c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 >The maximum ind
209d0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 ex number of any
209e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 [parameter] in
209f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
20a00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e .)^.**.** ^(<dt>
20a10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
20a20 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
20a30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20a40 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
20a50 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
20a60 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rs.</dd>)^.** </
20a70 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
20a80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
20a90 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
20aa0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
20ab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
20ac0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
20ad0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
20ae0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
20af0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
20b00 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
20b10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
20b20 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
20b30 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
20b40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
20b50 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
20b60 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
20b70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
20b80 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
20b90 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
20ba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
20bb0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
20bc0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
20bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
20be0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
20bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
20c00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
20c10 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
20c20 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
20c40 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
20c50 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
20c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20c70 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
20c80 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
20c90 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
20ca0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
20cb0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
20cc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
20cd0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
20ce0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
20cf0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
20d00 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
20d10 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
20d20 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
20d30 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
20d40 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
20d50 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
20d60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
20d70 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
20d80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
20d90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
20da0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
20db0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
20dc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
20dd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20de0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
20df0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
20e00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
20e10 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
20e20 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
20e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
20e40 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
20e50 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
20e60 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
20e70 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
20e80 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
20e90 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
20ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
20eb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
20ec0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
20ed0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
20ee0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
20ef0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
20f00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20f10 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
20f20 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 F-16..**.** ^If
20f30 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
20f40 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
20f50 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
20f60 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
20f70 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
20f80 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
20f90 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
20fa0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
20fb0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
20fc0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
20fd0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
20fe0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 . ^When nByte i
20ff0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
21000 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
21010 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
21020 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
21030 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
21040 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
21050 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
21060 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
21070 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
21080 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
21090 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
210a0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
210b0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
210c0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
210d0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
210e0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
210f0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
21100 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
21110 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
21120 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
21130 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
21140 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
21150 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
21160 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
21170 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a rminator bytes..
21180 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c **.** ^If pzTail
21190 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
211a0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 n *pzTail is mad
211b0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
211c0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 e first byte.**
211d0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
211e0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
211f0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
21200 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
21210 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 only.** compile
21220 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
21230 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f ment in zSql, so
21240 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 *pzTail is left
21250 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 pointing to.**
21260 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 what remains unc
21270 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ompiled..**.** ^
21280 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 *ppStmt is left
21290 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f pointing to a co
212a0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 mpiled [prepared
212b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
212c0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 can be.** execu
212d0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
212e0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 e3_step()]. ^If
212f0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
21300 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
21310 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
21320 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 ^If the input te
21330 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
21340 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
21350 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
21360 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
21370 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
21380 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
21390 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 ..** The calling
213a0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 procedure is re
213b0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 sponsible for de
213c0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 leting the compi
213d0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 led.** SQL state
213e0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
213f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
21400 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
21410 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
21420 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 * ppStmt may not
21430 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
21440 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 ^On success, the
21450 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
21460 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 () family of rou
21470 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
21480 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 LITE_OK];.** oth
21490 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
214a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
214b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
214c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
214d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
214e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
214f0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
21500 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
21510 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
21520 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
21530 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
21540 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
21550 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
21560 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
21570 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
21580 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
21590 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
215a0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
215b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
215c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
215d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
215e0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
215f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
21600 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
21610 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
21620 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
21630 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
21640 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
21650 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
21660 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
21670 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
21680 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
21690 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
216a0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
216b0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
216c0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
216d0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
216e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
216f0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
21700 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
21710 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
21720 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
21730 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 un it again..**
21740 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
21750 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 .** ^When an err
21760 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
21770 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
21780 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
21790 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
217a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
217b0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
217c0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 codes]. ^The le
217d0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
217e0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
217f0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
21800 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
21810 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
21820 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
21830 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 e.** and the app
21840 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 lication would h
21850 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
21860 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
21870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
21880 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 * in order to fi
21890 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
218a0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
218b0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
218c0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
218d0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
218e0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
218f0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
21900 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
21910 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
21920 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
21930 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
21940 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f c value bound to
21950 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f [parameter | ho
21960 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e st parameter] in
21970 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 the .** WHERE c
21980 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c lause might infl
21990 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 uence the choice
219a0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 of query plan f
219b0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a or a statement,.
219c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 ** then the stat
219d0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 ement will be au
219e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
219f0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 mpiled, as if th
21a00 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a ere had been .**
21a10 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
21a20 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 , on the first
21a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21a40 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 call following
21a50 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f any change.** to
21a60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
21a70 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e nd_text | bindin
21a80 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 gs] of that [par
21a90 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 ameter]. .** ^Th
21aa0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
21ab0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 of WHERE-clause
21ac0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 [parameter] mig
21ad0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
21ae0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 .** choice of q
21af0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 uery plan if the
21b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
21b10 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 e left-hand side
21b20 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 of a [LIKE].**
21b30 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 or [GLOB] operat
21b40 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 or or if the par
21b50 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 ameter is compar
21b60 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 ed to an indexed
21b70 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 column.** and t
21b80 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c he [SQLITE_ENABL
21b90 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 E_STAT2] compile
21ba0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
21bb0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 enabled..** the
21bc0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f .** </li>.** </o
21bd0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l>.*/.int sqlite
21be0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 3_prepare(. sql
21bf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
21c00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
21c10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
21c20 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
21c30 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
21c40 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
21c50 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
21c60 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
21c70 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
21c80 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
21c90 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
21ca0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
21cb0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
21cc0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
21cd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
21ce0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
21cf0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
21d00 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
21d10 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
21d20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21d30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
21d40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
21d50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
21d60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
21d70 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
21d80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
21d90 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
21da0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
21db0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
21dc0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
21dd0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
21de0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
21df0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
21e00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
21e10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
21e20 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
21e30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
21e40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
21e50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
21e60 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
21e70 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 re16(. sqlite3
21e80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
21e90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
21ea0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
21eb0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
21ec0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
21ed0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
21ee0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
21ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
21f00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
21f10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
21f20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
21f30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
21f40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
21f50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
21f60 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
21f70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
21f80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
21f90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
21fa0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
21fb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 _prepare16_v2(.
21fc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
21fd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
21fe0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
21ff0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
22000 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
22010 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
22020 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
22030 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
22040 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
22050 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
22060 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
22070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
22080 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
22090 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
220a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
220b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
220c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
220d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
220e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f of zSql */.);../
220f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
22100 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d etrieving Statem
22110 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 ent SQL.**.** ^T
22120 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
22130 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 n be used to ret
22140 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f rieve a saved co
22150 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e py of the origin
22160 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 al.** SQL text u
22170 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 sed to create a
22180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22190 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 ent] if that sta
221a0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f tement was.** co
221b0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 mpiled using eit
221c0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 her [sqlite3_pre
221d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
221e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
221f0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 _v2()]..*/.const
22200 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
22210 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ql(sqlite3_stmt
22220 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
22230 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
22240 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
22250 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 atement Writes T
22260 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a he Database.**.*
22270 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
22280 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 tmt_readonly(X)
22290 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
222a0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
222b0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 ) if.** and only
222c0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 if the [prepare
222d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d d statement] X m
222e0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 akes no direct c
222f0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 hanges to.** the
22300 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
22310 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a database file..*
22320 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b *.** Note that [
22330 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
22340 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
22350 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 s] or.** [virtua
22360 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 l tables] might
22370 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
22380 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 ase indirectly a
22390 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e s a side effect.
223a0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d .** ^(For exam
223b0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 ple, if an appli
223c0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 cation defines a
223d0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 function "eval(
223e0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c )" that .** call
223f0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 s [sqlite3_exec(
22400 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c )], then the fol
22410 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 lowing SQL state
22420 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 ment would.** ch
22430 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
22440 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 e file through s
22450 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a ide-effects:.**.
22460 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
22470 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 pre>.** SELEC
22480 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 T eval('DELETE F
22490 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 ROM t1') FROM t2
224a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
224b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
224c0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b ut because the [
224d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
224e0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 t does not chang
224f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
22500 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c ile.** directly,
22510 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
22520 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 adonly() would s
22530 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 till return true
22540 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 .)^.**.** ^Trans
22550 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 action control s
22560 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 tatements such a
22570 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d s [BEGIN], [COMM
22580 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c IT], [ROLLBACK],
22590 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c .** [SAVEPOINT],
225a0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 and [RELEASE] c
225b0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ause sqlite3_stm
225c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
225d0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 return true,.**
225e0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d since the statem
225f0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 ents themselves
22600 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 do not actually
22610 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 modify the datab
22620 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 ase but.** rathe
22630 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 r they control t
22640 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 he timing of whe
22650 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e n other statemen
22660 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a ts modify the .*
22670 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 * database. ^Th
22680 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b e [ATTACH] and [
22690 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e DETACH] statemen
226a0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a ts also cause.**
226b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
226c0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
226d0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 rn true since, w
226e0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 hile those state
226f0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 ments.** change
22700 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
22710 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 n of a database
22720 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 connection, they
22730 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a do not make .**
22740 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
22750 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 content of the d
22760 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e atabase files on
22770 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 disk..*/.int sq
22780 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
22790 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 nly(sqlite3_stmt
227a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
227b0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d CAPI3REF: Dynam
227c0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c ically Typed Val
227d0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 ue Object.** KEY
227e0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 WORDS: {protecte
227f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
22800 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 {unprotected sq
22810 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a lite3_value}.**.
22820 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 ** SQLite uses t
22830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
22840 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 object to repre
22850 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a sent all values.
22860 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 ** that can be s
22870 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 tored in a datab
22880 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 ase table. SQLit
22890 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 e uses dynamic t
228a0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 yping.** for the
228b0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 values it store
228c0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 s. ^Values stor
228d0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 ed in sqlite3_va
228e0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 lue objects.** c
228f0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 an be integers,
22900 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
22910 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 alues, strings,
22920 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a BLOBs, or NULL..
22930 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 **.** An sqlite3
22940 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 _value object ma
22950 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f y be either "pro
22960 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 tected" or "unpr
22970 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d otected"..** Som
22980 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 e interfaces req
22990 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 uire a protected
229a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 sqlite3_value.
229b0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 Other interface
229c0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 s.** will accept
229d0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 either a protec
229e0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ted or an unprot
229f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22a00 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e lue..** Every in
22a10 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 terface that acc
22a20 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c epts sqlite3_val
22a30 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 ue arguments spe
22a40 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 cifies.** whethe
22a50 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 r or not it requ
22a60 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 ires a protected
22a70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
22a80 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
22a90 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
22aa0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
22ab0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
22ac0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
22ad0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e is held. An in
22ae0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
22af0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
22b00 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
22b10 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
22b20 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
22b30 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
22b40 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
22b50 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
22b60 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
22b70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
22b80 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
22b90 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
22ba0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
22bb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
22bc0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
22bd0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
22be0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
22bf0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
22c00 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
22c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
22c20 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
22c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
22c40 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
22c50 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
22c60 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
22c70 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
22c80 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
22c90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
22ca0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
22cb0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
22cc0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
22cd0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
22ce0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
22cf0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
22d00 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
22d10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
22d20 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
22d30 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
22d40 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
22d50 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
22d60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22d70 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
22d80 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
22d90 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
22da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
22db0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
22dc0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
22dd0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
22de0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
22df0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
22e00 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
22e10 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
22e20 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
22e30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
22e40 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
22e50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
22e60 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
22e70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
22e80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
22e90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
22ea0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
22eb0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
22ec0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
22ed0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
22ee0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
22ef0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
22f00 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
22f10 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
22f20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
22f30 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
22f40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
22f50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
22f60 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
22f70 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
22f80 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
22f90 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
22fa0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
22fb0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e ct.**.** The con
22fc0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
22fd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
22fe0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
22ff0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
23000 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
23010 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f . ^A pointer to
23020 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 an sqlite3_cont
23030 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 ext object.** is
23040 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 always first pa
23050 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c rameter to [appl
23060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
23070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a SQL functions]..
23080 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
23090 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
230a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
230b0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 tation will pass
230c0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 this.** pointer
230d0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 through into ca
230e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
230f0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c result_int | sql
23100 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a ite3_result()],.
23110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 ** [sqlite3_aggr
23120 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d egate_context()]
23130 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f , [sqlite3_user_
23140 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c data()],.** [sql
23150 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
23160 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 handle()], [sqli
23170 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
23180 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 )],.** and/or [s
23190 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
231a0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 ta()]..*/.typede
231b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
231c0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
231d0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
231e0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 CAPI3REF: Bindi
231f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 ng Values To Pre
23200 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 pared Statements
23210 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
23220 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
23230 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
23240 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
23250 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
23260 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
23270 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
23280 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
23290 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e binding}.**.** ^
232a0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 (In the SQL stat
232b0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 ement text input
232c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
232d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 pare_v2()] and i
232e0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 ts variants,.**
232f0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 literals may be
23300 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 replaced by a [p
23310 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d arameter] that m
23320 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f atches one of fo
23330 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c llowing.** templ
23340 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ates:.**.** <ul>
23350 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
23360 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
23370 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
23380 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
23390 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
233a0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 ** In the templa
233b0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 tes above, NNN r
233c0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 epresents an int
233d0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
233e0 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 and VVV represe
233f0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 nts an alphanume
23400 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 ric identifier.)
23410 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f ^ ^The values o
23420 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d f these.** param
23430 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c eters (also call
23440 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 ed "host paramet
23450 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 er names" or "SQ
23460 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a L parameters").*
23470 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
23480 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
23490 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
234a0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
234b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
234c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
234d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
234e0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
234f0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
23500 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
23510 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
23520 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
23530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
23540 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
23550 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 iants..**.** ^Th
23560 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
23570 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
23580 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
23590 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a ter to be set..*
235a0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 * ^The leftmost
235b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 SQL parameter ha
235c0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
235d0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 ^When the same
235e0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 named.** SQL pa
235f0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 rameter is used
23600 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
23610 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
23620 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 quent.** occurre
23630 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 nces have the sa
23640 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 me index as the
23650 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 first occurrence
23660 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 ..** ^The index
23670 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 for named parame
23680 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b ters can be look
23690 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a ed up using the.
236a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
236b0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
236c0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 ()] API if desir
236d0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a ed. ^The index.
236e0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 ** for "?NNN" pa
236f0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 rameters is the
23700 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
23710 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 ^The NNN value
23720 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 must be between
23730 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 1 and the [sqlit
23740 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 e3_limit()].** p
23750 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 arameter [SQLITE
23760 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
23770 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 NUMBER] (default
23780 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a value: 999)..**
23790 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 .** ^The third a
237a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 rgument is the v
237b0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 alue to bind to
237c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
237d0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 *.** ^(In those
237e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 routines that ha
237f0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 ve a fourth argu
23800 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 ment, its value
23810 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
23820 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
23830 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 parameter. To
23840 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 be clear: the va
23850 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 lue is the.** nu
23860 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 mber of <u>bytes
23870 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 </u> in the valu
23880 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 e, not the numbe
23890 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
238a0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f )^.** ^If the fo
238b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
238c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 s negative, the
238d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 length of the st
238e0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e ring is.** the n
238f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 umber of bytes u
23900 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
23910 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
23920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 **.** ^The fifth
23930 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
23940 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
23950 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 , sqlite3_bind_t
23960 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 ext(), and.** sq
23970 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
23980 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 6() is a destruc
23990 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
239a0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
239b0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
239c0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
239d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
239e0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
239f0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
23a00 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
23a10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
23a20 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
23a30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
23a40 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 blob(),.** sqlit
23a50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 e3_bind_text(),
23a60 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
23a70 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 text16() fails.
23a80 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 .** ^If the fif
23a90 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a th argument is.*
23aa0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 * the special va
23ab0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 lue [SQLITE_STAT
23ac0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 IC], then SQLite
23ad0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
23ae0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
23af0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 is in static, u
23b00 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 nmanaged space a
23b10 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 nd does not need
23b20 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a to be freed..**
23b30 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
23b40 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 rgument has the
23b50 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 value [SQLITE_TR
23b60 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a ANSIENT], then.*
23b70 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 * SQLite makes i
23b80 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
23b90 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 opy of the data
23ba0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 immediately, bef
23bb0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 ore.** the sqlit
23bc0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
23bd0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a ine returns..**.
23be0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23bf0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 bind_zeroblob()
23c00 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 routine binds a
23c10 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e BLOB of length N
23c20 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c that.** is fill
23c30 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 ed with zeroes.
23c40 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 ^A zeroblob use
23c50 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 s a fixed amount
23c60 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a of memory.** (j
23c70 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 ust an integer t
23c80 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 o hold its size)
23c90 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 while it is bei
23ca0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a ng processed..**
23cb0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 Zeroblobs are i
23cc0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 ntended to serve
23cd0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 as placeholders
23ce0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 for BLOBs whose
23cf0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c .** content is l
23d00 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 ater written usi
23d10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ng.** [sqlite3_b
23d20 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 lob_open | incre
23d30 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d mental BLOB I/O]
23d40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 routines..** ^A
23d50 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 negative value
23d60 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 for the zeroblob
23d70 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 results in a ze
23d80 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a ro-length BLOB..
23d90 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 **.** ^If any of
23da0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
23db0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 d_*() routines a
23dc0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 re called with a
23dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
23de0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 for the [prepar
23df0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 ed statement] or
23e00 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 with a prepared
23e10 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 statement for w
23e20 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hich.** [sqlite3
23e30 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 _step()] has bee
23e40 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 n called more re
23e50 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c cently than [sql
23e60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a ite3_reset()],.*
23e70 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 * then the call
23e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
23e90 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 ITE_MISUSE]. If
23ea0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e any sqlite3_bin
23eb0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 d_().** routine
23ec0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 is passed a [pre
23ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23ee0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 that has been f
23ef0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a inalized, the.**
23f00 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
23f10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
23f20 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a y harmful..**.**
23f30 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e ^Bindings are n
23f40 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
23f50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
23f60 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
23f70 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 ^Unbound paramet
23f80 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 ers are interpre
23f90 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ted as NULL..**.
23fa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23fb0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 bind_* routines
23fc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
23fd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 K] on success or
23fe0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f an.** [error co
23ff0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 de] if anything
24000 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e goes wrong..** ^
24010 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 [SQLITE_RANGE] i
24020 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 s returned if th
24030 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 e parameter.** i
24040 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
24050 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f ange. ^[SQLITE_
24060 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
24070 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
24080 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ails..**.** See
24090 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
240a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
240b0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 unt()],.** [sqli
240c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
240d0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 er_name()], and
240e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
240f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
24100 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
24110 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 _bind_blob(sqlit
24120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
24130 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
24140 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
24150 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
24160 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 bind_double(sqli
24170 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
24180 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c double);.int sql
24190 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
241a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
241b0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 , int);.int sqli
241c0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 te3_bind_int64(s
241d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
241e0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
241f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
24200 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ind_null(sqlite3
24210 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e _stmt*, int);.in
24220 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
24230 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
24240 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 *, int, const ch
24250 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 ar*, int n, void
24260 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
24270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
24280 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
24290 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
242a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
242b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
242c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
242d0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
242e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c , int, const sql
242f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
24300 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
24310 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
24320 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
24330 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
24340 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 REF: Number Of S
24350 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a QL Parameters.**
24360 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
24370 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
24380 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
24390 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
243a0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
243b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
243c0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
243d0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
243e0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
243f0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
24400 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
24410 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
24420 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
24430 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
24440 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
24450 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
24460 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
24470 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
24480 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 r time..**.** ^(
24490 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
244a0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
244b0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
244c0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
244d0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
244e0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
244f0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
24500 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
24510 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
24520 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
24530 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
24540 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
24550 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 NN form are used
24560 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
24570 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
24580 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 st.)^.**.** See
24590 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
245a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
245b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
245c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
245d0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
245e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
245f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
24600 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ex()]..*/.int sq
24610 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
24620 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 eter_count(sqlit
24630 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
24640 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
24650 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d Of A Host Param
24660 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eter.**.** ^The
24670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
24680 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
24690 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
246a0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
246b0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
246c0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
246d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
246e0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
246f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
24700 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
24710 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
24720 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
24730 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
24740 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
24750 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
24760 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
24770 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
24780 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
24790 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
247a0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
247b0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
247c0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
247d0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
247e0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
247f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
24800 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
24810 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
24820 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
24830 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
24840 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
24850 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
24860 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
24870 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
24880 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
24890 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
248a0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
248b0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
248c0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
248d0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
248e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
248f0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
24900 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
24910 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
24920 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
24930 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
24940 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
24950 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
24960 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
24970 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
24980 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
24990 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
249a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
249b0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
249c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
249d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
249e0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
249f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
24a00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
24a10 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
24a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
24a30 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
24a40 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
24a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
24a60 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
24a70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
24a80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
24a90 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
24aa0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
24ab0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 en Name.**.** ^R
24ac0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
24ad0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 of an SQL parame
24ae0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 ter given its na
24af0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 me. ^The.** ind
24b00 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
24b10 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
24b20 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
24b30 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
24b40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
24b50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
24b60 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f ind()]. ^A zero
24b70 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
24b80 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
24b90 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
24ba0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 d. ^The paramet
24bb0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
24bc0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
24bd0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
24be0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
24bf0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
24c00 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
24c10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24c20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
24c30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
24c40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
24c50 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
24c60 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
24c70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
24c80 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
24c90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
24ca0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
24cb0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
24cc0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
24cd0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
24ce0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
24cf0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
24d00 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
24d10 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
24d20 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
24d30 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f tement.**.** ^Co
24d40 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
24d50 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
24d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
24d70 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
24d80 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
24d90 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
24da0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
24db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24dc0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 ]..** ^Use this
24dd0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
24de0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
24df0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f ters to NULL..*/
24e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 .int sqlite3_cle
24e10 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
24e20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
24e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
24e40 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
24e50 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
24e60 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
24e70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
24e80 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
24e90 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
24ea0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
24eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
24ec0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
24ed0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
24ee0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
24ef0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
24f00 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
24f10 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
24f20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
24f30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
24f40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
24f50 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
24f60 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 _column_count(sq
24f70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
24f80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
24f90 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 REF: Column Name
24fa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
24fb0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
24fc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
24fd0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
24fe0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
24ff0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
25000 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
25010 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
25020 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 ment. ^The sqli
25030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
25040 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 ).** interface r
25050 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
25060 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
25070 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
25080 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ng.** and sqlite
25090 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
250a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
250b0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
250c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
250d0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
250e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
250f0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 is the [prepare
25100 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
25110 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
25120 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
25130 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 tement. ^The sec
25140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
25150 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e the.** column n
25160 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 umber. ^The lef
25170 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 tmost column is
25180 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 number 0..**.**
25190 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
251a0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 ring pointer is
251b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 valid until eith
251c0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 er the [prepared
251d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 statement].** i
251e0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b s destroyed by [
251f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
25200 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
25210 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
25220 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
25230 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
25240 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
25250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
25260 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
25270 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
25280 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 the next call t
25290 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
252a0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 umn_name() or sq
252b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
252c0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d e16() on the sam
252d0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 e column..**.**
252e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ^If sqlite3_mall
252f0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e oc() fails durin
25300 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 g the processing
25310 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 of either routi
25320 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 ne.** (for examp
25330 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 le during a conv
25340 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d ersion from UTF-
25350 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 8 to UTF-16) the
25360 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
25370 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
25380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
25390 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c of a result col
253a0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 umn is the value
253b0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 of the "AS" cla
253c0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 use for.** that
253d0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 column, if there
253e0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 is an AS clause
253f0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
25400 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 o AS clause.** t
25410 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 hen the name of
25420 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e the column is un
25430 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 specified and ma
25440 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a y change from.**
25450 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 one release of
25460 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 SQLite to the ne
25470 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 xt..*/.const cha
25480 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
25490 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
254a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f tmt*, int N);.co
254b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
254c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
254d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
254e0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
254f0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
25500 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
25510 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
25520 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 These routines p
25530 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 rovide a means t
25540 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 o determine the
25550 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
25560 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f and.** table co
25570 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 lumn that is the
25580 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 origin of a par
25590 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 ticular result c
255a0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c olumn in.** [SEL
255b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a ECT] statement..
255c0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
255d0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
255e0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
255f0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
25600 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
25610 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
25620 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 tring. ^The _da
25630 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
25640 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
25650 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
25660 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
25670 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
25680 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
25690 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
256a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
256b0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
256c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
256d0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
256e0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
256f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
25700 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
25710 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
25720 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
25730 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
25740 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
25750 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
25760 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
25770 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
25780 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
25790 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
257a0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
257b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
257c0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
257d0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
257e0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
257f0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 ^The names retur
25800 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 ned are the orig
25810 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 inal un-aliased
25820 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 names of the.**
25830 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
25840 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a and column..**.
25850 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
25860 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 gument to these
25870 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 interfaces is a
25880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
25890 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 ent]..** ^These
258a0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
258b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
258c0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c ut the Nth resul
258d0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 t column returne
258e0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
258f0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
25900 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
25910 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
25920 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 ** ^The left-mos
25930 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 t column is colu
25940 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 mn 0 for these r
25950 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
25960 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
25970 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 n returned by th
25980 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
25990 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a n expression or.
259a0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 ** subquery and
259b0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 is not a column
259c0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 value, then all
259d0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f of these functio
259e0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c ns return.** NUL
259f0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 L. ^These routi
25a00 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 ne might also re
25a10 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d turn NULL if a m
25a20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
25a30 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 error.** occurs
25a40 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 . ^Otherwise, t
25a50 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e hey return the n
25a60 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 ame of the attac
25a70 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 hed database, ta
25a80 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d ble,.** or colum
25a90 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 n that query res
25aa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 ult column was e
25ab0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a xtracted from..*
25ac0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c *.** ^As with al
25ad0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
25ae0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 PIs, those whose
25af0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 names end with
25b00 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
25b10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
25b20 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 rings and the ot
25b30 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 her functions re
25b40 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a turn UTF-8..**.*
25b50 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 * ^These APIs ar
25b60 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 e only available
25b70 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
25b80 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
25b90 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
25ba0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
25bb0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
25bc0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a ocessor symbol..
25bd0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
25be0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
25bf0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
25c00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
25c10 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
25c20 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
25c30 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
25c40 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
25c50 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
25c60 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
25c70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ined..**.** If t
25c80 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
25c90 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
25ca0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
25cb0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
25cc0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
25cd0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
25ce0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
25cf0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
25d00 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
25d10 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
25d20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
25d30 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
25d40 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
25d50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
25d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
25d70 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
25d80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
25d90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
25da0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
25db0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
25dc0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
25dd0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
25de0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
25df0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
25e00 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
25e10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
25e20 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
25e30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
25e40 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
25e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
25e60 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
25e70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
25e80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
25e90 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
25ea0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
25eb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
25ec0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
25ed0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
25ee0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
25ef0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 **.** ^(The firs
25f00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
25f10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
25f20 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
25f30 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
25f40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
25f50 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
25f60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
25f70 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
25f80 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
25f90 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
25fa0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
25fb0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
25fc0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
25fd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
25fe0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
25ff0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
26000 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 rned.)^ ^If the
26010 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
26020 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
26030 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
26040 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
26050 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
26060 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
26070 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
26080 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 string is alway
26090 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e s UTF-8 encoded.
260a0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 .**.** ^(For exa
260b0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
260c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
260d0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
260e0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
260f0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
26100 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
26110 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
26120 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
26130 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
26140 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
26150 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
26160 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
26170 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
26180 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
26190 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
261a0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
261b0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
261c0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
261d0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a mn (i==0).)^.**.
261e0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
261f0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 dynamic run-time
26200 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 typing. ^So ju
26210 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
26220 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
26230 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
26240 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
26250 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
26260 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
26270 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
26280 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
26290 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
262a0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
262b0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
262c0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
262d0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
262e0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 . ^Type.** is a
262f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 ssociated with i
26300 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 ndividual values
26310 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 , not with the c
26320 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 ontainers.** use
26330 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 d to hold those
26340 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 values..*/.const
26350 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
26360 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 olumn_decltype(s
26370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
26380 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
26390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
263a0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 cltype16(sqlite3
263b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
263c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 .** CAPI3REF: Ev
263d0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 aluate An SQL St
263e0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 atement.**.** Af
263f0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
26400 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
26410 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
26420 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
26430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
26440 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
26450 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
26460 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
26470 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
26480 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
26490 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
264a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
264b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
264c0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
264d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
264e0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
264f0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
26500 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
26510 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
26520 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
26530 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
26540 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
26550 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
26560 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
26570 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
26580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
26590 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
265a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
265b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
265c0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
265d0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
265e0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
265f0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
26600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
26610 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
26620 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
26630 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
26640 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
26650 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
26660 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
26670 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
26680 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
26690 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
266a0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
266b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
266c0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
266d0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
266e0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
266f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
26700 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
26710 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
26720 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
26730 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
26740 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
26750 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
26760 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
26770 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
26780 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
26790 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
267a0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
267b0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
267c0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
267d0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
267e0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
267f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
26800 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
26810 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
26820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
26830 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
26840 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
26850 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
26860 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
26870 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
26880 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
26890 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
268a0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
268b0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
268c0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 s within a.** ex
268d0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
268e0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 on then you shou
268f0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 ld rollback the
26900 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f transaction befo
26910 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 re.** continuing
26920 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
26930 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
26940 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
26950 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
26960 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
26970 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
26980 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
26990 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
269a0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
269b0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
269c0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
269d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
269e0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
269f0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
26a00 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
26a10 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
26a20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 .**.** ^If the S
26a30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 QL statement bei
26a40 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 ng executed retu
26a50 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 rns any data, th
26a60 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a en [SQLITE_ROW].
26a70 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 ** is returned e
26a80 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 ach time a new r
26a90 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 ow of data is re
26aa0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 ady for processi
26ab0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ng by the.** cal
26ac0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ler. The values
26ad0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 may be accessed
26ae0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d using the [colum
26af0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
26b00 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ns]..** sqlite3_
26b10 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 step() is called
26b20 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 again to retrie
26b30 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 ve the next row
26b40 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e of data..**.** ^
26b50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
26b60 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
26b70 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
26b80 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
26b90 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
26ba0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
26bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
26bc0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
26bd0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
26be0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
26bf0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
26c00 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
26c10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
26c20 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
26c30 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
26c40 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
26c50 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f c error code (fo
26c60 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 r example,.** [S
26c70 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
26c80 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
26c90 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 ], [SQLITE_CORRU
26ca0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 PT], and so fort
26cb0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 h).** can be obt
26cc0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 ained by calling
26cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
26ce0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 )] on the.** [pr
26cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26d00 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 ]. ^In the "v2"
26d10 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
26d20 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
26d30 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
26d40 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
26d50 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
26d60 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
26d70 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
26d80 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
26d90 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
26da0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
26db0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
26dc0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
26dd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26de0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a ent] that has.**
26df0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 already been [s
26e00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
26e10 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 | finalized] or
26e20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a on one that had.
26e30 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
26e40 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
26e50 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
26e60 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
26e70 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
26e80 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
26e90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
26ea0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
26eb0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
26ec0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
26ed0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
26ee0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
26ef0 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 For all versions
26f00 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f of SQLite up to
26f10 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 and including 3
26f20 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 .6.23.1, a call
26f30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
26f40 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 eset()] was requ
26f50 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 ired after sqlit
26f60 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e e3_step() return
26f70 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f ed anything.** o
26f80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
26f90 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e E_ROW] before an
26fa0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 y subsequent inv
26fb0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 ocation of.** sq
26fc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 lite3_step(). F
26fd0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 ailure to reset
26fe0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
26ff0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a tement using .**
27000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
27010 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 )] would result
27020 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 in an [SQLITE_MI
27030 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f SUSE] return fro
27040 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 m.** sqlite3_ste
27050 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 p(). But after
27060 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 version 3.6.23.1
27070 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
27080 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e began.** callin
27090 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
270a0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ()] automaticall
270b0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d y in this circum
270c0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a stance rather.**
270d0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 than returning
270e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
270f0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f This is not co
27100 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 nsidered a compa
27110 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 tibility.** brea
27120 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 k because any ap
27130 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 plication that e
27140 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 ver receives an
27150 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 SQLITE_MISUSE er
27160 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e ror.** is broken
27170 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 by definition.
27180 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 The [SQLITE_OMI
27190 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d T_AUTORESET] com
271a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
271b0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 .** can be used
271c0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c to restore the l
271d0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a egacy behavior..
271e0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 **.** <b>Goofy I
271f0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c nterface Alert:<
27200 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 /b> In the legac
27210 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
27220 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a sqlite3_step().
27230 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 ** API always re
27240 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 turns a generic
27250 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c error code, [SQL
27260 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c ITE_ERROR], foll
27270 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 owing any.** err
27280 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 or other than [S
27290 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 QLITE_BUSY] and
272a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
272b0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a You must call.
272c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
272d0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
272e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 _finalize()] in
272f0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e order to find on
27300 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 e of the.** spec
27310 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
27320 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 s] that better d
27330 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
27340 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 or..** We admit
27350 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 that this is a g
27360 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 oofy design. Th
27370 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 e problem has be
27380 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 en fixed.** with
27390 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
273a0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 ace. If you pre
273b0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 pare all of your
273c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
273d0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ** using either
273e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
273f0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
27400 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
27410 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 )] instead.** of
27420 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
27430 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
27440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
27450 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 pare16()] interf
27460 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 aces,.** then th
27470 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
27480 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 [error codes] ar
27490 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 e returned direc
274a0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 tly.** by sqlite
274b0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 3_step(). The u
274c0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 se of the "v2" i
274d0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
274e0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 mmended..*/.int
274f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
27500 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
27510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
27520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
27530 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a in a result set.
27540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27550 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
27560 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
27570 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
27580 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
27590 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f ** current row o
275a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
275b0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
275c0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
275d0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 If prepared stat
275e0 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 ement P does not
275f0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 have results re
27600 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ady to return.**
27610 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 (via calls to t
27620 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
27630 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 mn_int | sqlite3
27640 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a _column_*()] of.
27650 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 ** interfaces) t
27660 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 hen sqlite3_data
27670 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e _count(P) return
27680 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s 0..** ^The sql
27690 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
276a0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 P) routine also
276b0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 returns 0 if P i
276c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
276d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
276e0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d : [sqlite3_colum
276f0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e n_count()].*/.in
27700 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 t sqlite3_data_c
27710 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
27720 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
27730 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 * CAPI3REF: Fund
27740 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 amental Datatype
27750 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 s.** KEYWORDS: S
27760 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a QLITE_TEXT.**.**
27770 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 ^(Every value i
27780 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 n SQLite has one
27790 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 of five fundame
277a0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a ntal datatypes:.
277b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
277c0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 i> 64-bit signed
277d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e integer.** <li>
277e0 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 64-bit IEEE flo
277f0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
27800 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e er.** <li> strin
27810 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a g.** <li> BLOB.*
27820 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c * <li> NULL.** <
27830 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 /ul>)^.**.** The
27840 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
27850 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
27860 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
27870 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
27880 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
27890 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
278a0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
278b0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
278c0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
278d0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
278e0 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
278f0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
27900 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
27910 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
27920 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
27930 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
27940 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
27950 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
27960 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
27970 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
27980 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
27990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
279a0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
279b0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
279c0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
279d0 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
279e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
279f0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
27a00 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
27a10 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
27a20 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
27a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27a40 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
27a50 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 om A Query.** KE
27a60 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 YWORDS: {column
27a70 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
27a80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
27a90 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 utines form the
27aa0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 "result set" int
27ab0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 erface..**.** ^T
27ac0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
27ad0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
27ae0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
27af0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
27b00 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
27b10 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
27b20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 ^In every case
27b30 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
27b40 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a nt is a pointer.
27b50 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 ** to the [prepa
27b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
27b70 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 hat is being eva
27b80 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c luated (the [sql
27b90 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 ite3_stmt*].** t
27ba0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
27bb0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
27bc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
27bd0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
27be0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 nts).** and the
27bf0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
27c00 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
27c10 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
27c20 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
27c30 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
27c40 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 turned. ^The lef
27c50 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 tmost column of
27c60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 the result set h
27c70 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a as the index 0..
27c80 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f ** ^The number o
27c90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
27ca0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 result can be d
27cb0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a etermined using.
27cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
27cd0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a mn_count()]..**.
27ce0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
27cf0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
27d00 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 currently point
27d10 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c to a valid row,
27d20 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f or if the.** co
27d30 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 lumn index is ou
27d40 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 t of range, the
27d50 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
27d60 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ned..** These ro
27d70 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 utines may only
27d80 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 be called when t
27d90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
27da0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
27db0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
27dc0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
27dd0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 ROW] and neither
27de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
27df0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 et()] nor [sqlit
27e00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 e3_finalize()] h
27e10 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
27e20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a subsequently..**
27e30 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 If any of these
27e40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
27e50 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
27e60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
27e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
27e80 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
27e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
27ea0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a ] has returned.*
27eb0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 * something othe
27ec0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
27ed0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 OW], the results
27ee0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
27ef0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 ** If [sqlite3_s
27f00 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
27f10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
27f20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
27f30 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 ()].** are calle
27f40 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 d from a differe
27f50 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 nt thread while
27f60 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
27f70 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e tines.** are pen
27f80 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ding, then the r
27f90 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
27fa0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
27fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
27fc0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 type() routine r
27fd0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 eturns the.** [S
27fe0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
27ff0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
28000 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
28010 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
28020 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
28030 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
28040 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
28050 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
28060 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
28070 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
28080 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
28090 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
280a0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
280b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
280c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
280d0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
280e0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
280f0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
28100 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
28110 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
28120 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
28130 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
28140 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
28150 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
28160 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
28170 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
28180 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
28190 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
281a0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
281b0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
281c0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
281d0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
281e0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
281f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
28200 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
28210 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 -8 string then t
28220 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
28230 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 n_bytes().** rou
28240 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
28250 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
28260 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
28270 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
28280 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
28290 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
282a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
282b0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
282c0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
282d0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
282e0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
282f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
28300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
28310 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
28320 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
28330 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
28340 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
28350 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
28360 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
28370 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 alue to a UTF-8
28380 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
28390 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
283a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
283b0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
283c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
283d0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
283e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
283f0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
28400 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
28410 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
28420 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 UTF-16 string t
28430 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
28440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
28450 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
28460 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
28470 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
28480 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
28490 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
284a0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 t is a UTF-8 str
284b0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
284c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
284d0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 () converts.** t
284e0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 he string to UTF
284f0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 -16 and then ret
28500 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
28510 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
28520 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
28530 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
28540 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
28550 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 mn_bytes16() use
28560 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
28570 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
28580 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
28590 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 to a UTF-16 stri
285a0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
285b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
285c0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
285d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
285e0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
285f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
28600 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 lumn_bytes16() r
28610 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
28620 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 ** ^The values r
28630 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
28640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
28650 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c ()] and .** [sql
28660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
28670 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e s16()] do not in
28680 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
28690 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 erminators at th
286a0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
286b0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c string. ^For cl
286c0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 arity: the value
286d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
286e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
286f0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 _bytes()] and [s
28700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
28710 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 tes16()] are the
28720 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 number of.** by
28730 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e tes in the strin
28740 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 g, not the numbe
28750 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
28760 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 .**.** ^Strings
28770 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
28780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
28790 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f ) and sqlite3_co
287a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a lumn_text16(),.*
287b0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 * even empty str
287c0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 ings, are always
287d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 zero terminated
287e0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a . ^The return.*
287f0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
28800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
28810 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
28820 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e ngth BLOB is a N
28830 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
28840 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 ** ^The object r
28850 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
28860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
28870 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e ()] is an.** [un
28880 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
28890 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
288a0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 An unprotected
288b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
288c0 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c bject.** may onl
288d0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b y be used with [
288e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
288f0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
28900 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
28910 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 )]..** If the [u
28920 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
28930 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
28940 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
28950 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
28960 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 value()] is used
28970 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 in any other wa
28980 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c y, including cal
28990 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 ls.** to routine
289a0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
289b0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 value_int()], [s
289c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
289d0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
289e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
289f0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ()], then the be
28a00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
28a10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
28a20 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
28a30 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
28a40 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
28a50 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a ropriate. ^For.
28a60 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
28a70 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
28a80 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
28a90 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
28aa0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
28ab0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
28ac0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
28ad0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
28ae0 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
28af0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
28b00 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 matically. ^(Th
28b10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
28b20 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
28b30 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
28b40 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
28b50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
28b60 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
28b70 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
28b80 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
28b90 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
28ba0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
28bb0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
28bc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
28bd0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
28be0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
28bf0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
28c00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
28c10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
28c20 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
28c30 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
28c40 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
28c50 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
28c60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
28c70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
28c80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
28c90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
28ca0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
28cb0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
28cc0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
28cd0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
28ce0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
28cf0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
28d00 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
28d10 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
28d20 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
28d30 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
28d40 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
28d50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
28d60 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
28d70 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
28d80 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
28d90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
28da0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
28db0 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
28dc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
28dd0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
28de0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
28df0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
28e00 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
28e10 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
28e20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
28e30 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
28e40 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
28e50 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
28e60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
28e70 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
28e80 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
28e90 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
28ea0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
28eb0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
28ec0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
28ed0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
28ee0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
28ef0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
28f00 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
28f10 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
28f20 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
28f30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
28f40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
28f50 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
28f60 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
28f70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
28f80 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
28f90 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
28fa0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
28fb0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
28fc0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
28fd0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 quote>)^.**.** T
28fe0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d he table above m
28ff0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 akes reference t
29000 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 o standard C lib
29010 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 rary functions a
29020 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f toi().** and ato
29030 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 f(). SQLite doe
29040 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 s not really use
29050 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
29060 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a . It has its.**
29070 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 own equivalent
29080 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 internal routine
29090 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 s. The atoi() a
290a0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 nd atof() names
290b0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 are.** used in t
290c0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 he table for bre
290d0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 vity and because
290e0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 they are famili
290f0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 ar to most.** C
29100 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a programmers..**.
29110 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
29120 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
29130 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
29140 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
29150 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
29160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29170 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
29180 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
29190 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
291a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
291b0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
291c0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
291d0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
291e0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
291f0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
29200 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
29210 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
29220 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
29230 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
29240 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
29250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
29260 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
29270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
29280 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
29290 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
292a0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
292b0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
292c0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
292d0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
292e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
292f0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
29300 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
29310 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
29320 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
29330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
29340 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
29350 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
29360 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
29370 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
29380 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
29390 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
293a0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
293b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
293c0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
293d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
293e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
293f0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
29400 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
29410 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
29420 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
29430 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e </ul>.**.** ^Con
29440 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
29450 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
29460 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
29470 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
29480 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
29490 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
294a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
294b0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
294c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
294d0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
294e0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 prior pointer r
294f0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 eferences will h
29500 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
29510 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
29520 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
29530 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
29540 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
29550 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
29560 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
29570 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
29580 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
29590 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
295a0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
295b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
295c0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 st and easiest t
295d0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 o remember polic
295e0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
295f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
29600 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
29610 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
29620 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
29630 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
29640 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
29650 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
29660 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
29670 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
29680 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
29690 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
296a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
296b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
296c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
296d0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
296e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
296f0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
29700 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
29710 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
29720 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
29730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
29740 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
29750 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
29760 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
29770 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
29780 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
29790 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
297a0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
297b0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
297c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
297d0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
297e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
297f0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
29800 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
29810 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
29820 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
29830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
29840 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
29850 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
29860 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
29870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
29880 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
29890 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
298a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
298b0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
298c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
298d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
298e0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 .** ^The pointer
298f0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 s returned are v
29900 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 alid until a typ
29910 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 e conversion occ
29920 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 urs as.** descri
29930 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e bed above, or un
29940 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 til [sqlite3_ste
29950 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
29960 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
29970 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
29980 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 e()] is called.
29990 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 ^The memory spa
299a0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ce used to hold
299b0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 strings.** and B
299c0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 LOBs is freed au
299d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f tomatically. Do
299e0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 <b>not</b> pass
299f0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 the pointers re
29a00 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 turned.** [sqlit
29a10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
29a20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ], [sqlite3_colu
29a30 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e mn_text()], etc.
29a40 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 into.** [sqlite
29a50 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_free()]..**.**
29a60 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 ^(If a memory a
29a70 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 llocation error
29a80 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
29a90 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 e evaluation of
29aa0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 any.** of these
29ab0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 routines, a defa
29ac0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 ult value is ret
29ad0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 urned. The defa
29ae0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 ult value.** is
29af0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 either the integ
29b00 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 er 0, the floati
29b10 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 ng point number
29b20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 0.0, or a NULL.*
29b30 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 * pointer. Subs
29b40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
29b50 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
29b60 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a ()] will return.
29b70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
29b80 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f ].)^.*/.const vo
29b90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
29ba0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f mn_blob(sqlite3_
29bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
29bc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
29bd0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 lumn_bytes(sqlit
29be0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
29bf0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
29c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
29c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
29c20 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 nt iCol);.double
29c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29c40 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
29c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
29c60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
29c70 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f umn_int(sqlite3_
29c80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
29c90 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
29ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
29cb0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
29cc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 t*, int iCol);.c
29cd0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
29ce0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
29cf0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f mn_text(sqlite3_
29d00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
29d10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
29d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
29d30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
29d40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
29d50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
29d60 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 _type(sqlite3_st
29d70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
29d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 sqlite3_value *s
29d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
29da0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
29db0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f *, int iCol);../
29dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
29dd0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 estroy A Prepare
29de0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
29df0 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ct.**.** ^The sq
29e00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
29e10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
29e20 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 led to delete a
29e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29e40 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ent]..** ^If the
29e50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
29e60 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 luation of the s
29e70 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 tatement encount
29e80 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f ered no errors o
29e90 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 r.** or if the s
29ea0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
29eb0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
29ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
29ed0 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
29ee0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
29ef0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
29f00 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
29f10 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
29f20 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
29f30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
29f40 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
29f50 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
29f60 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
29f70 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
29f80 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
29f90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
29fa0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
29fb0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
29fc0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
29fd0 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
29fe0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
29ff0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
2a000 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
2a010 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
2a020 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
2a030 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
2a040 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2a050 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
2a060 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
2a070 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
2a080 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
2a090 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
2a0a0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
2a0b0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
2a0c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
2a0d0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
2a0e0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
2a0f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2a100 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2a110 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
2a120 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
2a130 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
2a140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
2a150 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
2a160 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
2a170 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
2a180 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
2a190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
2a1a0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
2a1b0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2a1c0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2a1d0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2a1e0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
2a1f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2a200 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
2a210 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2a220 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
2a230 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
2a240 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
2a250 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
2a260 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
2a270 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
2a280 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
2a290 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
2a2a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2a2b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2a2c0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
2a2d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
2a2e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a2f0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
2a300 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
2a310 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
2a320 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
2a330 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
2a340 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
2a350 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
2a360 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
2a370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2a380 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2a390 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
2a3a0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
2a3b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2a3c0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
2a3d0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
2a3e0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
2a3f0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
2a400 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2a410 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
2a420 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
2a430 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
2a440 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
2a450 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
2a460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a470 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
2a480 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
2a490 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
2a4a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
2a4b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2a4c0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2a4d0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
2a4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a4f0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
2a500 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
2a510 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
2a520 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
2a530 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
2a540 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
2a550 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
2a560 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2a570 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2a580 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2a590 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
2a5a0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2a5b0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2a5c0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
2a5d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a5e0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
2a5f0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
2a600 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2a610 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
2a620 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
2a630 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
2a640 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2a650 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
2a660 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
2a670 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
2a680 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
2a690 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
2a6a0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
2a6b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2a6c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2a6d0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
2a6e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2a6f0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
2a700 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
2a710 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
2a720 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
2a730 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2a740 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
2a750 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2a760 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2a770 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
2a780 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2a790 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2a7a0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
2a7b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
2a7c0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2a7d0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2a7e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2a7f0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2a800 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2a810 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2a820 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2a830 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2a840 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2a850 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2a860 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2a870 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
2a880 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
2a890 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
2a8a0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2a8b0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
2a8c0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
2a8d0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
2a8e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
2a8f0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
2a900 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
2a910 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
2a920 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
2a930 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
2a940 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
2a950 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
2a960 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
2a970 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
2a980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a990 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
2a9a0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
2a9b0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
2a9c0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
2a9d0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
2a9e0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
2a9f0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
2aa00 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
2aa10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2aa20 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
2aa30 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
2aa40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2aa50 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
2aa60 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2aa70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2aa80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
2aa90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2aaa0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
2aab0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
2aac0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
2aad0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
2aae0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
2aaf0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
2ab00 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
2ab10 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
2ab20 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
2ab30 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
2ab40 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
2ab50 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
2ab60 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
2ab70 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
2ab80 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
2ab90 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
2aba0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
2abb0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
2abc0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
2abd0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
2abe0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
2abf0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
2ac00 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
2ac10 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2ac20 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2ac30 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
2ac40 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2ac50 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
2ac60 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
2ac70 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
2ac80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2ac90 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
2aca0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
2acb0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
2acc0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
2acd0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
2ace0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
2acf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2ad00 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
2ad10 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
2ad20 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
2ad30 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
2ad40 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
2ad50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2ad60 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2ad70 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
2ad80 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
2ad90 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
2ada0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
2adb0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
2adc0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
2add0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
2ade0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
2adf0 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 eters. Every SQ
2ae00 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2ae10 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 mentation must b
2ae20 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
2ae30 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 * with UTF-8, UT
2ae40 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2ae50 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2ae60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2ae70 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2ae80 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2ae90 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2aea0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 nother. ^An app
2aeb0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
2aec0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
2aed0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2aee0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
2aef0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
2af00 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
2af10 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2af20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
2af30 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
2af40 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
2af50 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
2af60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2af70 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2af80 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
2af90 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
2afa0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
2afb0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
2afc0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
2afd0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
2afe0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
2aff0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
2b000 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2b010 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
2b020 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
2b030 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
2b040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
2b050 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
2b060 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
2b070 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 NY]..**.** ^(The
2b080 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2b090 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
2b0a0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
2b0b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2b0c0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
2b0d0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
2b0e0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
2b0f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2b100 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a user_data()].)^.
2b110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 **.** ^The sixth
2b120 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 , seventh and ei
2b130 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c ghth parameters,
2b140 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
2b150 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
2b160 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
2b170 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
2b180 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2b190 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2b1a0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2b1b0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c e. ^A scalar SQL
2b1c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2b1d0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2b1e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
2b1f0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
2b200 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly; NULL pointer
2b210 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 s must be passed
2b220 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
2b230 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
2b240 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 meters. ^An aggr
2b250 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2b260 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
2b270 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2b280 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 xStep.** and xF
2b290 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f inal and NULL po
2b2a0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 inter must be pa
2b2b0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
2b2c0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 ^To delete an ex
2b2d0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2b2e0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2b2f0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 ate, pass NULL p
2b300 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 ointers for all
2b310 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a three function.*
2b320 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a * callbacks..**.
2b330 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 ** ^(If the nint
2b340 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2b350 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2b360 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e nction_v2() is n
2b370 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e ot NULL,.** then
2b380 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f it is destructo
2b390 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
2b3a0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
2b3b0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 er. .** The dest
2b3c0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 ructor is invoke
2b3d0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 d when the funct
2b3e0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 ion is deleted,
2b3f0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a either by being.
2b400 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 ** overloaded or
2b410 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
2b420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
2b430 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 oses.)^.** ^The
2b440 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c destructor is al
2b450 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 so invoked if th
2b460 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c e call to.** sql
2b470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2b480 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e tion_v2() fails.
2b490 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 .** ^When the de
2b4a0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
2b4b0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 k of the tenth p
2b4c0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f arameter is invo
2b4d0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 ked, it.** is pa
2b4e0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 ssed a single ar
2b4f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
2b500 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 a copy of the ap
2b510 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a plication data .
2b520 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 ** pointer which
2b530 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 was the fifth p
2b540 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2b550 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2b560 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 ion_v2()..**.**
2b570 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 ^It is permitted
2b580 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
2b590 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2b5a0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2b5b0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
2b5c0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
2b5d0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
2b5e0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
2b5f0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
2b600 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
2b610 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2b620 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c encodings. ^SQL
2b630 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
2b640 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
2b650 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
2b660 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
2b670 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
2b680 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
2b690 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 n is used. ^A f
2b6a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2b6b0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
2b6c0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
2b6d0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
2b6e0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
2b6f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
2b700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2b710 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
2b720 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 nArg. ^A funct
2b730 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 ion where the pr
2b740 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
2b750 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 oding.** matches
2b760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2b770 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 coding is a bett
2b780 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e er.** match than
2b790 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
2b7a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 e the encoding i
2b7b0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a s different. .*
2b7c0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 * ^A function wh
2b7d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
2b7e0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 difference is b
2b7f0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 etween UTF16le a
2b800 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 nd UTF16be.** is
2b810 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 a closer match
2b820 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
2b830 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
2b840 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
2b850 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 .** between UTF8
2b860 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a and UTF16..**.*
2b870 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 * ^Built-in func
2b880 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
2b890 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
2b8a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2b8b0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
2b8c0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 .** ^An applicat
2b8d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2b8e0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
2b8f0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a d to call other.
2b900 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
2b910 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 aces. However,
2b920 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 such calls must
2b930 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 not.** close the
2b940 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2b950 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a tion nor finaliz
2b960 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 e or reset the p
2b970 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
2b980 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 ment in which th
2b990 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 e function is ru
2b9a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nning..*/.int sq
2b9b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2b9c0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
2b9d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
2b9e0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
2b9f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
2ba00 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
2ba10 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
2ba20 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
2ba30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2ba40 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2ba50 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
2ba60 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
2ba70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2ba80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2ba90 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
2baa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
2bab0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
2bac0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
2bad0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
2bae0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
2baf0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
2bb00 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
2bb10 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
2bb20 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
2bb30 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
2bb40 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
2bb50 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
2bb60 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
2bb70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
2bb80 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
2bb90 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
2bba0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
2bbb0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
2bbc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2bbd0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
2bbe0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
2bbf0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
2bc00 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
2bc10 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
2bc20 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
2bc30 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
2bc40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2bc50 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2bc60 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2bc70 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
2bc80 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2bc90 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2bca0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
2bcb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2bcc0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
2bcd0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
2bce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
2bcf0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
2bd00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2bd10 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
2bd20 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
2bd30 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
2bd40 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
2bd50 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
2bd60 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
2bd70 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
2bd80 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
2bd90 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
2bda0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
2bdb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
2bdc0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
2bdd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
2bde0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
2bdf0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
2be00 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
2be10 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
2be20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
2be30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
2be40 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
2be50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2be60 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
2be70 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
2be80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2be90 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
2bea0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
2beb0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
2bec0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
2bed0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
2bee0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
2bef0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
2bf00 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
2bf10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
2bf20 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
2bf30 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
2bf40 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
2bf50 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
2bf60 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
2bf70 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
2bf80 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
2bf90 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
2bfa0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
2bfb0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
2bfc0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
2bfd0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
2bfe0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
2bff0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
2c000 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
2c010 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
2c020 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
2c030 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
2c040 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2c050 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2c060 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
2c070 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
2c080 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
2c090 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
2c0a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
2c0b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
2c0c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
2c0d0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
2c0e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
2c0f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
2c100 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
2c110 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
2c120 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
2c130 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
2c140 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
2c150 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
2c160 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
2c170 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2c180 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
2c190 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
2c1a0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
2c1b0 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 ,void*,sqlite3_i
2c1c0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt64);.#endif../
2c1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2c1e0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e btaining SQL Fun
2c1f0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 ction Parameter
2c200 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Values.**.** The
2c210 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
2c220 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
2c230 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
2c240 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
2c250 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
2c260 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
2c270 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
2c280 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
2c290 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
2c2a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
2c2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
2c2c0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
2c2d0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
2c2e0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
2c2f0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
2c300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
2c310 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
2c320 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
2c330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
2c340 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
2c350 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
2c360 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
2c370 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
2c380 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 gates..** The 3r
2c390 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
2c3a0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
2c3b0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
2c3c0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
2c3d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2c3e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
2c3f0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
2c400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2c410 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
2c420 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2c430 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
2c440 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2c450 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
2c460 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
2c470 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
2c480 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
2c490 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
2c4a0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
2c4b0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
2c4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2c4d0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
2c4e0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
2c4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
2c500 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
2c510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
2c520 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
2c530 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
2c540 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 avior..**.** ^Th
2c550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
2c560 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 k just like the
2c570 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 corresponding [c
2c580 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
2c590 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 ctions].** excep
2c5a0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f t that these ro
2c5b0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 utines take a si
2c5c0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 ngle [protected
2c5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2c5e0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 bject.** pointer
2c5f0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 instead of a [s
2c600 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f qlite3_stmt*] po
2c610 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 inter and an int
2c620 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 eger column numb
2c630 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
2c640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2c650 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 t16() interface
2c660 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 extracts a UTF-1
2c670 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
2c680 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
2c690 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
2c6a0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a machine. ^The.
2c6b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2c6c0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 _text16be() and
2c6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2c6e0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 xt16le() interfa
2c6f0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 ces.** extract U
2c700 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 TF-16 strings as
2c710 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
2c720 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
2c730 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
2c740 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
2c750 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
2c760 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 pe() interface a
2c770 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 ttempts to apply
2c780 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 .** numeric affi
2c790 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 nity to the valu
2c7a0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 e. This means t
2c7b0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 hat an attempt i
2c7c0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e s.** made to con
2c7d0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 vert the value t
2c7e0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 o an integer or
2c7f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 floating point.
2c800 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f If.** such a co
2c810 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 nversion is poss
2c820 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 ible without los
2c830 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e s of information
2c840 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f (in other.** wo
2c850 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 rds, if the valu
2c860 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 e is a string th
2c870 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 at looks like a
2c880 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 number).** then
2c890 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 the conversion i
2c8a0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 s performed. Ot
2c8b0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 herwise no conve
2c8c0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a rsion occurs..**
2c8d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 The [SQLITE_INT
2c8e0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d EGER | datatype]
2c8f0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f after conversio
2c900 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
2c910 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 .**.** Please pa
2c920 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 y particular att
2c930 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 ention to the fa
2c940 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e ct that the poin
2c950 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ter returned.**
2c960 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 from [sqlite3_va
2c970 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 lue_blob()], [sq
2c980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2c990 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2c9a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2c9b0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c ()] can be inval
2c9c0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 idated by a subs
2c9d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a equent call to.*
2c9e0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
2c9f0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 _bytes()], [sqli
2ca00 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
2ca10 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 6()], [sqlite3_v
2ca20 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
2ca30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
2ca40 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a ue_text16()]..**
2ca50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2ca60 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
2ca70 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
2ca80 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 thread as.** the
2ca90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 SQL function th
2caa0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 at supplied the
2cab0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d [sqlite3_value*]
2cac0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a parameters..*/.
2cad0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2cae0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 te3_value_blob(s
2caf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2cb00 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2cb10 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
2cb20 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
2cb30 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
2cb40 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
2cb50 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 *);.double sqlit
2cb60 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 e3_value_double(
2cb70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2cb80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
2cb90 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
2cba0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f alue*);.sqlite3_
2cbb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 int64 sqlite3_va
2cbc0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 lue_int64(sqlite
2cbd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
2cbe0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2cbf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2cc00 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 xt(sqlite3_value
2cc10 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
2cc20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2cc30 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c xt16(sqlite3_val
2cc40 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
2cc50 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
2cc60 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
2cc70 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
2cc80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
2cc90 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
2cca0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
2ccb0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
2ccc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
2ccd0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
2cce0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
2ccf0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
2cd00 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
2cd10 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
2cd20 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
2cd30 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 Context.**.** I
2cd40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
2cd50 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 f aggregate SQL
2cd60 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 functions use th
2cd70 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f is.** routine to
2cd80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
2cd90 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 for storing the
2cda0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 ir state..**.**
2cdb0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
2cdc0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
2cdd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
2cde0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 N) routine is ca
2cdf0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 lled .** for a p
2ce00 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 articular aggreg
2ce10 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 ate function, SQ
2ce20 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 Lite.** allocate
2ce30 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a s N of memory, z
2ce40 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d eroes out that m
2ce50 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
2ce60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
2ce70 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 to the new memor
2ce80 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e y. ^On second an
2ce90 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
2cea0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2ceb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2cec0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
2ced0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
2cee0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a tion instance,.*
2cef0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 * the same buffe
2cf00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 r is returned.
2cf10 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 Sqlite3_aggregat
2cf20 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e e_context() is n
2cf30 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 ormally.** calle
2cf40 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
2cf50 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 invocation of th
2cf60 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b e xStep callback
2cf70 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a and then one.**
2cf80 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 last time when
2cf90 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
2cfa0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ack is invoked.
2cfb0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 ^(When no rows
2cfc0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 match.** an aggr
2cfd0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 egate query, the
2cfe0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 xStep() callbac
2cff0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 k of the aggrega
2d000 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 te function.** i
2d010 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
2d020 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e never called an
2d030 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 d xFinal() is ca
2d040 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 lled exactly onc
2d050 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 e..** In those c
2d060 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 ases, sqlite3_ag
2d070 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2d080 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 ) might be calle
2d090 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 d for the.** fir
2d0a0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 st time from wit
2d0b0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a hin xFinal().)^.
2d0c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2d0d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2d0e0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
2d0f0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c e returns a NULL
2d100 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 pointer if N is
2d110 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 .** less than or
2d120 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f equal to zero o
2d130 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c r if a memory al
2d140 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
2d150 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
2d160 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
2d170 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
2d180 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
2d190 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
2d1a0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
2d1b0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
2d1c0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
2d1d0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
2d1e0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
2d1f0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
2d200 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
2d210 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2d220 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
2d230 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
2d240 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
2d250 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
2d260 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
2d270 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
2d280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2d290 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2d2a0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 frees the memory
2d2b0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a allocated by .*
2d2c0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
2d2d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 ate_context() wh
2d2e0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
2d2f0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
2d300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
2d310 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
2d320 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
2d330 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
2d340 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
2d350 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
2d360 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
2d370 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
2d380 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 the xStep or xFi
2d390 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 nal callback rou
2d3a0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
2d3b0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
2d3c0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a te.** function..
2d3d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2d3e0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
2d3f0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
2d400 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
2d410 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ** the aggregate
2d420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
2d430 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
2d440 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 d *sqlite3_aggre
2d450 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
2d460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2d470 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
2d480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
2d490 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
2d4a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ions.**.** ^The
2d4b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
2d4c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
2d4d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
2d4e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
2d4f0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
2d500 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
2d510 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
2d520 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
2d530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2d540 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
2d550 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2d560 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
2d570 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
2d580 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
2d590 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
2d5a0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
2d5b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
2d5c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
2d5d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
2d5e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
2d5f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
2d600 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2d610 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
2d620 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
2d630 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
2d640 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
2d650 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
2d660 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
2d670 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
2d680 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
2d690 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 The sqlite3_cont
2d6a0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 ext_db_handle()
2d6b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2d6c0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
2d6d0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
2d6e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2d6f0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 ection] (the 1st
2d700 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
2d710 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
2d720 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2d730 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2d740 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2d750 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
2d760 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
2d770 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
2d780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
2d790 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
2d7a0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 */.sqlite3 *sqli
2d7b0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
2d7c0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
2d7d0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
2d7e0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
2d7f0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
2d800 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c a.**.** The foll
2d810 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 owing two functi
2d820 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
2d830 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 by scalar SQL fu
2d840 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
2d850 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
2d860 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
2d870 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
2d880 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
2d890 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
2d8a0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
2d8b0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
2d8c0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
2d8d0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
2d8e0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
2d8f0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
2d900 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
2d910 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
2d920 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a ved. This may.**
2d930 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 be used, for ex
2d940 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 ample, to add a
2d950 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
2d960 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c on matching scal
2d970 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ar.** function.
2d980 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
2d990 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
2d9a0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 lar expression i
2d9b0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d s stored as.** m
2d9c0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
2d9d0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
2d9e0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
2d9f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
2da00 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
2da10 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
2da20 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
2da30 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
2da40 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
2da50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
2da60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2da70 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
2da80 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
2da90 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
2daa0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
2dab0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
2dac0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
2dad0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
2dae0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
2daf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2db00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2db10 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
2db20 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
2db30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
2db40 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
2db50 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
2db60 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
2db70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2db80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
2db90 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 ^If no metadata
2dba0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a has been ever.*
2dbb0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 * been set for t
2dbc0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 he Nth argument
2dbd0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c of the function,
2dbe0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 or if the corre
2dbf0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 sponding.** func
2dc00 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 tion parameter h
2dc10 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 as changed since
2dc20 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 the meta-data w
2dc30 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 as set,.** then
2dc40 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
2dc50 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 ata() returns a
2dc60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2dc70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2dc80 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _set_auxdata() i
2dc90 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 nterface saves t
2dca0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 he metadata.** p
2dcb0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 ointed to by its
2dcc0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 3rd parameter a
2dcd0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 s the metadata f
2dce0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 or the N-th.** a
2dcf0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 rgument of the a
2dd00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2dd10 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 ed function. Su
2dd20 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
2dd30 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 s to sqlite3_get
2dd40 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 _auxdata() might
2dd50 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 return this dat
2dd60 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 a, if it has.**
2dd70 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 not been destroy
2dd80 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 ed..** ^If it is
2dd90 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 not NULL, SQLit
2dda0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 e will invoke th
2ddb0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 e destructor.**
2ddc0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 function given b
2ddd0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 y the 4th parame
2dde0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 ter to sqlite3_s
2ddf0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a et_auxdata() on.
2de00 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 ** the metadata
2de10 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 when the corresp
2de20 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 onding function
2de30 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 parameter change
2de40 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 s.** or when the
2de50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 SQL statement c
2de60 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 ompletes, whiche
2de70 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e ver comes first.
2de80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 .**.** SQLite is
2de90 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 free to call th
2dea0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 e destructor and
2deb0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f drop metadata o
2dec0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 n any.** paramet
2ded0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 er of any functi
2dee0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 on at any time.
2def0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 ^The only guara
2df00 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 ntee is that.**
2df10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 the destructor w
2df20 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 ill be called be
2df30 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 fore the metadat
2df40 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a a is dropped..**
2df50 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
2df60 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
2df70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
2df80 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
2df90 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f for.** expressio
2dfa0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 ns that are cons
2dfb0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 tant at compile
2dfc0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 time. This inclu
2dfd0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 des literal.** v
2dfe0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d alues and [param
2dff0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 eters].)^.**.**
2e000 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2e010 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
2e020 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
2e030 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
2e040 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2e050 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 is running..*/.v
2e060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 oid *sqlite3_get
2e070 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
2e080 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
2e090 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
2e0a0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
2e0b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2e0c0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
2e0d0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
2e0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2e0f0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
2e100 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
2e110 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a uctor Behavior.*
2e120 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
2e130 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
2e140 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
2e150 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
2e160 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
2e170 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
2e180 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
2e190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
2e1a0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 b()]. ^If the d
2e1b0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
2e1c0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
2e1d0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
2e1e0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
2e1f0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
2e200 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
2e210 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
2e220 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
2e230 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
2e240 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 d. ^The.** SQLI
2e250 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
2e260 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
2e270 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
2e280 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
2e290 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
2e2a0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
2e2b0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
2e2c0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
2e2d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
2e2e0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
2e2f0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
2e300 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
2e310 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
2e320 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
2e330 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
2e340 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 compilers. See
2e350 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a ticket #2191..*
2e360 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 /.typedef void (
2e370 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 *sqlite3_destruc
2e380 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 tor_type)(void*)
2e390 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
2e3a0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 _STATIC ((s
2e3b0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
2e3c0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e r_type)0).#defin
2e3d0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 e SQLITE_TRANSIE
2e3e0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 NT ((sqlite3_d
2e3f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d estructor_type)-
2e400 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 1)../*.** CAPI3R
2e410 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 EF: Setting The
2e420 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c Result Of An SQL
2e430 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Function.**.**
2e440 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
2e450 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
2e460 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
2e470 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
2e480 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
2e490 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
2e4a0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2e4c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
2e4d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2e4e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
2e4f0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
2e500 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
2e510 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
2e520 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
2e530 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
2e540 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
2e550 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
2e560 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
2e570 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
2e580 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
2e590 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2e5a0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
2e5b0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
2e5c0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
2e5d0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
2e5e0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
2e5f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2e600 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
2e610 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
2e620 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
2e630 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
2e640 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2e650 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
2e660 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
2e670 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
2e680 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
2e690 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
2e6a0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
2e6b0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
2e6c0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
2e6d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
2e6e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2e6f0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 zeroblob() inter
2e700 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 faces set the re
2e710 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
2e720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2e730 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
2e740 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e e a BLOB contain
2e750 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 ing all zero.**
2e760 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 bytes and N byte
2e770 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 s in size, where
2e780 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 N is the value
2e790 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d of the 2nd param
2e7a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
2e7b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2e7c0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
2e7d0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
2e7e0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
2e7f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2e800 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
2e810 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
2e820 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
2e830 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
2e840 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
2e860 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
2e870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2e880 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f rror16() functio
2e890 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 ns.** cause the
2e8a0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 implemented SQL
2e8b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f function to thro
2e8c0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a w an exception..
2e8d0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
2e8e0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
2e8f0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
2e900 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
2e910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2e920 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
2e930 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
2e940 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
2e950 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
2e960 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 essage. ^SQLite
2e970 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
2e980 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
2e990 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
2e9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2e9b0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 r() as UTF-8. ^S
2e9c0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 QLite.** interpr
2e9d0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 ets the string f
2e9e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
2e9f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 lt_error16() as
2ea00 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
2ea10 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 .** byte order.
2ea20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
2ea30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2ea40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2ea50 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2ea60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
2ea70 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
2ea80 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
2ea90 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
2eaa0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
2eab0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
2eac0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
2ead0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
2eae0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2eaf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
2eb00 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a lt_error() or.**
2eb10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2eb20 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e error16() is non
2eb30 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 -negative then S
2eb40 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 QLite takes that
2eb50 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 many.** bytes (
2eb60 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
2eb70 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
2eb80 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 ameter as the er
2eb90 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 ror message..**
2eba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
2ebb0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
2ebc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2ebd0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 rror16().** rout
2ebe0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 ines make a priv
2ebf0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
2ec00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
2ec10 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 xt before.** the
2ec20 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 y return. Hence
2ec30 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 , the calling fu
2ec40 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c nction can deall
2ec50 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 ocate or.** modi
2ec60 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 fy the text afte
2ec70 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 r they return wi
2ec80 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e thout harm..** ^
2ec90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2eca0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 lt_error_code()
2ecb0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 function changes
2ecc0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a the error code.
2ecd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 ** returned by S
2ece0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c QLite as a resul
2ecf0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e t of an error in
2ed00 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 a function. ^B
2ed10 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
2ed20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
2ed30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e SQLITE_ERROR. ^
2ed40 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
2ed50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 l to sqlite3_res
2ed60 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
2ed70 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
2ed80 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 _error16() reset
2ed90 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
2eda0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 to SQLITE_ERROR
2edb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2edc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 ite3_result_toob
2edd0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 ig() interface c
2ede0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 auses SQLite to
2edf0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a throw an error.*
2ee00 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 * indicating tha
2ee10 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c t a string or BL
2ee20 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 OB is too long t
2ee30 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a o represent..**.
2ee40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2ee50 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 result_nomem() i
2ee60 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
2ee70 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
2ee80 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
2ee90 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
2eea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
2eeb0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 failed..**.** ^T
2eec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2eed0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
2eee0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
2eef0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
2ef00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2ef10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
2ef20 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
2ef30 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
2ef40 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
2ef50 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
2ef60 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 t..** ^The sqlit
2ef70 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
2ef80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
2ef90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2efa0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
2efb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2efc0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
2efd0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
2efe0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
2eff0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
2f000 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
2f010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2f020 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
2f030 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
2f040 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
2f050 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
2f060 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2f070 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
2f080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
2f0a0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ), sqlite3_resul
2f0b0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 t_text16(),.** s
2f0c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2f0d0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 xt16le(), and sq
2f0e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2f0f0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 t16be() interfac
2f100 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 es.** set the re
2f110 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
2f120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2f130 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
2f140 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 o be.** a text s
2f150 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 tring which is r
2f160 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 epresented as UT
2f170 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 F-8, UTF-16 nati
2f180 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a ve byte order,.*
2f190 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 * UTF-16 little
2f1a0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 endian, or UTF-1
2f1b0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 6 big endian, re
2f1c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
2f1d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
2f1e0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
2f1f0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
2f200 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
2f210 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
2f220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2f230 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
2f240 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 es..** ^If the 3
2f250 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
2f260 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
2f270 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
2f280 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 ces.** is negati
2f290 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ve, then SQLite
2f2a0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 takes result tex
2f2b0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 t from the 2nd p
2f2c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f arameter.** thro
2f2d0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
2f2e0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
2f2f0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 ^If the 3rd par
2f300 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
2f310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2f320 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
2f330 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
2f340 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 , then as many b
2f350 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
2f360 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 ters) of the tex
2f370 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 t.** pointed to
2f380 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
2f390 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 eter are taken a
2f3a0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f s the applicatio
2f3b0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e n-defined.** fun
2f3c0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a ction result..**
2f3d0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
2f3e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
2f3f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2f400 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
2f410 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
2f420 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
2f430 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
2f440 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
2f450 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
2f460 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
2f470 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
2f480 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
2f490 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
2f4a0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
2f4b0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
2f4c0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
2f4d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
2f4e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
2f4f0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
2f500 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
2f510 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
2f520 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
2f530 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
2f540 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
2f550 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
2f560 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
2f570 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
2f580 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
2f590 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
2f5a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
2f5b0 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
2f5c0 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
2f5d0 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
2f5e0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
2f5f0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
2f600 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
2f610 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
2f620 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
2f630 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
2f640 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
2f650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
2f660 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
2f670 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
2f680 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
2f690 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
2f6a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
2f6b0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
2f6c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
2f6d0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
2f6e0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
2f6f0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
2f700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2f710 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
2f720 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
2f730 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
2f740 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2f750 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
2f760 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
2f770 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
2f780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2f790 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
2f7a0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
2f7b0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
2f7c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
2f7d0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
2f7e0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
2f7f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
2f800 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
2f810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
2f820 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
2f830 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
2f840 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
2f850 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
2f860 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
2f870 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
2f880 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
2f890 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
2f8a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2f8b0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
2f8c0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
2f8d0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
2f8e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2f8f0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
2f900 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
2f910 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
2f920 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2f930 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
2f940 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
2f950 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
2f960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
2f970 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
2f980 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
2f990 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
2f9a0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
2f9b0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
2f9c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
2f9d0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
2f9e0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
2f9f0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
2fa00 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
2fa10 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
2fa20 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
2fa30 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 result_blob(sqli
2fa40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
2fa50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
2fa60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2fa70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2fa80 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 sult_double(sqli
2fa90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f te3_context*, do
2faa0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 uble);.void sqli
2fab0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2fac0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2fad0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
2fae0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
2faf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
2fb00 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
2fb10 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
2fb20 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
2fb30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2fb40 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f _toobig(sqlite3_
2fb50 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 context*);.void
2fb60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2fb70 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 rror_nomem(sqlit
2fb80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
2fb90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2fba0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c t_error_code(sql
2fbb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2fbc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
2fbd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
2fbe0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2fbf0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
2fc00 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
2fc10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2fc20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
2fc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2fc40 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 sult_null(sqlite
2fc50 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
2fc60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2fc70 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
2fc80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
2fc90 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
2fca0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
2fcb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2fcc0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
2fcd0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
2fce0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
2fcf0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
2fd00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2fd10 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
2fd20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
2fd30 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
2fd40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
2fd50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2fd60 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
2fd70 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
2fd80 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
2fd90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
2fda0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2fdb0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 _value(sqlite3_c
2fdc0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
2fdd0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 _value*);.void s
2fde0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
2fdf0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
2fe00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
2fe10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fe20 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
2fe30 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
2fe40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
2fe50 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
2fe60 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
2fe70 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
2fe80 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
2fe90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2fea0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
2feb0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
2fec0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
2fed0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
2fee0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
2fef0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
2ff00 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
2ff10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
2ff20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
2ff30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
2ff40 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
2ff50 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
2ff60 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
2ff70 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
2ff80 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
2ff90 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
2ffa0 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
2ffb0 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
2ffc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
2ffd0 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
2ffe0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
2fff0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
30000 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
30010 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
30020 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
30030 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
30040 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
30050 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
30060 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
30070 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
30080 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
30090 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
300a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
300b0 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
300c0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
300d0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
300e0 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
300f0 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
30100 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
30110 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
30120 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
30130 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
30140 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
30150 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
30160 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
30170 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
30180 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
30190 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
301a0 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
301b0 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
301c0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
301d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
301e0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
301f0 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
30200 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
30210 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
30220 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
30230 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
30240 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
30250 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
30260 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
30270 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
30280 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
30290 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
302a0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
302b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
302c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
302d0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
302e0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
302f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
30300 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
30310 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
30320 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
30330 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
30340 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
30350 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
30360 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
30370 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
30380 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
30390 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
303a0 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
303b0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
303c0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
303d0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
303e0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
303f0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
30400 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
30410 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
30420 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
30430 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
30440 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
30450 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
30460 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
30470 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
30480 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
30490 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
304a0 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
304b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
304c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
304d0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
304e0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
304f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
30500 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
30510 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
30520 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
30530 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
30540 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
30550 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
30560 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
30570 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
30580 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
30590 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
305a0 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
305b0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
305c0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
305d0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
305e0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
305f0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
30600 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
30610 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
30620 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
30630 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
30640 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
30650 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
30660 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
30670 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
30680 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
30690 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
306a0 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
306b0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
306c0 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
306d0 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
306e0 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
306f0 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
30700 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
30710 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
30720 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
30730 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
30740 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
30750 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
30760 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
30770 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
30780 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
30790 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
307a0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
307b0 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
307c0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
307d0 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
307e0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
307f0 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
30800 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
30810 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
30820 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
30830 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
30840 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
30850 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
30860 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
30870 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
30880 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
30890 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
308a0 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
308b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
308c0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
308d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
308e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
308f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
30900 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
30910 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
30920 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
30930 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
30940 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
30950 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
30960 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
30970 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
30980 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
30990 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
309a0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
309b0 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
309c0 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
309d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
309e0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
309f0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
30a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
30a10 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
30a20 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
30a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
30a40 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
30a50 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
30a60 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
30a70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
30a80 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
30a90 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
30aa0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
30ab0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
30ac0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
30ad0 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
30ae0 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
30af0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
30b00 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
30b10 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
30b20 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
30b30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
30b40 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
30b50 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
30b60 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
30b70 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
30b80 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
30b90 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
30ba0 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
30bb0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
30bc0 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
30bd0 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
30be0 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
30bf0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
30c00 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
30c10 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
30c20 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
30c30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
30c40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
30c50 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
30c60 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
30c70 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
30c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
30c90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 ate_collation(.
30ca0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
30cb0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
30cc0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
30cd0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
30ce0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
30cf0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
30d00 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
30d10 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 t void*).);.int
30d20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
30d30 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 ollation_v2(. s
30d40 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
30d50 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
30d60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
30d70 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 . void *pArg,.
30d80 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
30d90 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
30da0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
30db0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
30dc0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
30dd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
30de0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
30df0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
30e00 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
30e10 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
30e20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
30e30 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
30e40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
30e50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
30e60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
30e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30e80 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
30e90 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a d Callbacks.**.*
30ea0 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 * ^To avoid havi
30eb0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
30ec0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
30ed0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
30ee0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
30ef0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
30f00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
30f10 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
30f20 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
30f30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
30f40 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e ection] to be in
30f50 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
30f60 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c n undefined coll
30f70 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
30f80 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a e is required..*
30f90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e *.** ^If the fun
30fa0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 ction is registe
30fb0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 red using the sq
30fc0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
30fd0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a needed() API,.**
30fe0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 then it is pass
30ff0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 ed the names of
31000 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
31010 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 ion sequences as
31020 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f strings.** enco
31030 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 ded in UTF-8. ^I
31040 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 f sqlite3_collat
31050 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 ion_needed16() i
31060 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e s used,.** the n
31070 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 ames are passed
31080 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 as UTF-16 in mac
31090 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 hine native byte
310a0 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 order..** ^A ca
310b0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e ll to either fun
310c0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 ction replaces t
310d0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c he existing coll
310e0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c ation-needed cal
310f0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 lback..**.** ^(W
31100 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
31110 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
31120 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
31130 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
31140 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
31150 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
31160 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
31170 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
31180 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
31190 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
311a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
311b0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
311c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
311d0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
311e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
311f0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
31200 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
31210 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
31220 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
31230 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
31240 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
31250 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
31260 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
31270 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
31280 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
31290 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
312a0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
312b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
312c0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ce.)^.**.** The
312d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
312e0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
312f0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
31300 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
31310 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
31320 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
31330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
31340 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
31350 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
31360 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
31370 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2()]..*/.int sql
31380 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
31390 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
313a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
313b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
313c0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
313d0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
313e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
313f0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
31400 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
31410 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
31420 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
31430 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
31440 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
31450 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 .#ifdef SQLITE_H
31460 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 AS_CODEC./*.** S
31470 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 pecify the key f
31480 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 or an encrypted
31490 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 database. This
314a0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 routine should b
314b0 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 e.** called righ
314c0 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f t after sqlite3_
314d0 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 open()..**.** Th
314e0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
314f0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
31500 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
31510 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
31520 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
31530 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
31540 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 _key(. sqlite3
31550 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
31560 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
31570 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
31580 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
31590 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
315a0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 /* The key
315b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 */.);../*.** Cha
315c0 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 nge the key on a
315d0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e n open database.
315e0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 If the current
315f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
31600 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 .** encrypted, t
31610 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
31620 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 encrypt it. If
31630 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 pNew==0 or nNew
31640 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 ==0, the.** data
31650 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 base is decrypte
31660 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 d..**.** The cod
31670 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
31680 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
31690 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
316a0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
316b0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
316c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
316d0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
316e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
316f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
31700 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
31710 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
31720 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
31730 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 /* The new key
31740 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 */.);../*.** Sp
31750 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 ecify the activa
31760 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 tion key for a S
31770 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e EE database. Un
31780 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 less .** activat
31790 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 ed, none of the
317a0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c SEE routines wil
317b0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
317c0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
317d0 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 _see(. const ch
317e0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 ar *zPassPhrase
317f0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 /* Activa
31800 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 tion phrase */.)
31810 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 ;.#endif..#ifdef
31820 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 SQLITE_ENABLE_C
31830 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 EROD./*.** Speci
31840 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f fy the activatio
31850 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f n key for a CERO
31860 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c D database. Unl
31870 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
31880 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 d, none of the C
31890 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 EROD routines wi
318a0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 ll work..*/.void
318b0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 sqlite3_activat
318c0 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 e_cerod(. const
318d0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 char *zPassPhra
318e0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 se /* Act
318f0 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a ivation phrase *
31900 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a /.);.#endif../*.
31910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
31920 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
31930 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a or A Short Time.
31940 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
31950 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 3_sleep() functi
31960 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 on causes the cu
31970 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 rrent thread to
31980 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f suspend executio
31990 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 n.** for at leas
319a0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 t a number of mi
319b0 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 lliseconds speci
319c0 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 fied in its para
319d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 meter..**.** If
319e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
319f0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 stem does not su
31a00 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 pport sleep requ
31a10 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c ests with.** mil
31a20 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 lisecond time re
31a30 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 solution, then t
31a40 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 he time will be
31a50 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a rounded up to.**
31a60 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
31a70 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ond. The number
31a80 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
31a90 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
31aa0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 y.** requested f
31ab0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e rom the operatin
31ac0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 g system is retu
31ad0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c rned..**.** ^SQL
31ae0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
31af0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 his interface by
31b00 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c calling the xSl
31b10 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 eep().** method
31b20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
31b30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
31b40 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c ect. If the xSl
31b50 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 eep() method.**
31b60 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 of the default V
31b70 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d FS is not implem
31b80 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c ented correctly,
31b90 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e or not implemen
31ba0 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 ted at.** all, t
31bb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
31bc0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 of sqlite3_slee
31bd0 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 p() may deviate
31be0 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 from the descrip
31bf0 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 tion.** in the p
31c00 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
31c10 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 hs..*/.int sqlit
31c20 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
31c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31c40 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
31c50 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
31c60 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a rary Files.**.**
31c70 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ^(If this globa
31c80 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
31c90 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
31ca0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
31cb0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
31cc0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
31cd0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
31ce0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
31cf0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
31d00 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 by SQLite when
31d10 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e using a built-in
31d20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
31d30 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 VFS].** will be
31d40 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 placed in that d
31d50 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 irectory.)^ ^If
31d60 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
31d70 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
31d80 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
31d90 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
31da0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
31db0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
31dc0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
31dd0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
31de0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
31df0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
31e00 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 ariable in more
31e10 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 than one.** thre
31e20 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 ad at a time. I
31e30 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
31e40 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 read or modify
31e50 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
31e60 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 if a [database
31e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
31e80 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 eing used at the
31e90 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 same time in a
31ea0 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 separate.** thre
31eb0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 ad..** It is int
31ec0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
31ed0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 variable be set
31ee0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 once.** as part
31ef0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 of process initi
31f00 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 alization and be
31f10 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 fore any SQLite
31f20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 interface.** rou
31f30 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 tines have been
31f40 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 called and that
31f50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 this variable re
31f60 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a main unchanged.*
31f70 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a * thereafter..**
31f80 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 .** ^The [temp_s
31f90 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
31fa0 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 ragma] may modif
31fb0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
31fc0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 and cause.** it
31fd0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f to point to memo
31fe0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
31ff0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
32000 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 ]. ^Furthermore
32010 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 ,.** the [temp_s
32020 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
32030 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 ragma] always as
32040 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 sumes that any s
32050 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 tring.** that th
32060 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e is variable poin
32070 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e ts to is held in
32080 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
32090 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
320a0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 e3_malloc] and t
320b0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 he pragma may at
320c0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 tempt to free th
320d0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 at memory.** usi
320e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
320f0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 ]..** Hence, if
32100 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 this variable is
32110 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 modified direct
32120 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 ly, either it sh
32130 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 ould be.** made
32140 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 NULL or made to
32150 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 point to memory
32160 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
32170 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a qlite3_malloc].*
32180 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 * or else the us
32190 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 e of the [temp_s
321a0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
321b0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 ragma] should be
321c0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c avoided..*/.SQL
321d0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 ITE_EXTERN char
321e0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 *sqlite3_temp_di
321f0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 rectory;../*.**
32200 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 CAPI3REF: Test F
32210 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d or Auto-Commit M
32220 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ode.** KEYWORDS:
32230 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 {autocommit mod
32240 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e}.**.** ^The sq
32250 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
32260 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 mmit() interface
32270 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
32280 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 o or.** zero if
32290 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 the given databa
322a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
322b0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 or is not in au
322c0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a tocommit mode,.*
322d0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
322e0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
322f0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 e is on by defau
32300 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d lt..** ^Autocomm
32310 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
32320 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d led by a [BEGIN]
32330 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e statement..** ^
32340 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
32350 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 is re-enabled by
32360 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b a [COMMIT] or [
32370 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a ROLLBACK]..**.**
32380 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 If certain kind
32390 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 s of errors occu
323a0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 r on a statement
323b0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d within a multi-
323c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 statement.** tra
323d0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 nsaction (errors
323e0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 including [SQLI
323f0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_FULL], [SQLIT
32400 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 E_IOERR],.** [SQ
32410 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
32420 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 LITE_BUSY], and
32430 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
32440 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 T]) then the.**
32450 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 transaction migh
32460 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b t be rolled back
32470 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
32480 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f The only way to
32490 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 .** find out whe
324a0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f ther SQLite auto
324b0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
324c0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
324d0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
324e0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
324f0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
32500 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
32510 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 r thread changes
32520 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 the autocommit
32530 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 status of the da
32540 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
32550 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
32560 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
32570 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
32580 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 urn value.** is
32590 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e undefined..*/.in
325a0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 t sqlite3_get_au
325b0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 tocommit(sqlite3
325c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
325d0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 REF: Find The Da
325e0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 tabase Handle Of
325f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
32600 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ement.**.** ^The
32610 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
32620 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 le interface ret
32630 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 urns the [databa
32640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
32650 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 andle.** to whic
32660 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 h a [prepared st
32670 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 atement] belongs
32680 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 . ^The [databas
32690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
326a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
326b0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 ite3_db_handle i
326c0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 s the same [data
326d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
326e0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 .** that was the
326f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
32700 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
32710 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
32720 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 call (or its va
32730 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 riants) that was
32740 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 used to.** crea
32750 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
32760 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c in the first pl
32770 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ace..*/.sqlite3
32780 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 *sqlite3_db_hand
32790 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
327a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
327b0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 EF: Find the nex
327c0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 t prepared state
327d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ment.**.** ^This
327e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
327f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
32800 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 the next [prepar
32810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 ed statement] af
32820 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 ter.** pStmt ass
32830 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
32840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
32850 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 ction] pDb. ^If
32860 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a pStmt is NULL.*
32870 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 * then this inte
32880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
32890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 pointer to the f
328a0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 irst prepared st
328b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 atement.** assoc
328c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 iated with the d
328d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
328e0 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 on pDb. ^If no
328f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32900 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 nt.** satisfies
32910 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f the conditions o
32920 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
32930 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e it returns NULL.
32940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 .**.** The [data
32950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
32960 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 pointer D in a
32970 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
32980 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c te3_next_stmt(D,
32990 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 S)] must refer t
329a0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 o an open databa
329b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
329c0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c and in particul
329d0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 ar must not be a
329e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
329f0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a /.sqlite3_stmt *
32a00 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
32a10 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 t(sqlite3 *pDb,
32a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
32a30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
32a40 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e I3REF: Commit An
32a50 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 d Rollback Notif
32a60 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
32a70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
32a80 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
32a90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
32aa0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
32ab0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f k.** function to
32ac0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
32ad0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
32ae0 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 on is [COMMIT |
32af0 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e committed]..** ^
32b00 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
32b10 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
32b20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 all to sqlite3_c
32b30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 ommit_hook().**
32b40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
32b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32b60 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
32b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32b80 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 rollback_hook()
32b90 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
32ba0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a ers a callback.*
32bb0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 * function to be
32bc0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
32bd0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
32be0 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 is [ROLLBACK | r
32bf0 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 olled back]..**
32c00 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 ^Any callback se
32c10 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 t by a previous
32c20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
32c30 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a rollback_hook().
32c40 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
32c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32c60 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
32c70 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 n..** ^The pArg
32c80 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 argument is pass
32c90 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
32ca0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e e callback..** ^
32cb0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
32cc0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b on a commit hook
32cd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
32ce0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 s non-zero,.** t
32cf0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 hen the commit i
32d00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
32d10 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a a rollback..**.
32d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32d30 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c commit_hook(D,C,
32d40 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 P) and sqlite3_r
32d50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 ollback_hook(D,C
32d60 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a ,P) functions.**
32d70 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 return the P ar
32d80 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 gument from the
32d90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 previous call of
32da0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
32db0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d on.** on the sam
32dc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
32dd0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 ection] D, or NU
32de0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 LL for.** the fi
32df0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 rst call for eac
32e00 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e h function on D.
32e10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 .**.** The callb
32e20 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ack implementati
32e30 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 on must not do a
32e40 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
32e50 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
32e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32e70 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
32e80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 the callback.
32e90 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
32ea0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
32eb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32ec0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
32ed0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
32ee0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
32ef0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
32f00 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
32f10 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
32f20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c commit.** or rol
32f30 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 lback hook in th
32f40 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
32f50 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
32f60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
32f70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
32f80 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
32f90 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
32fa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32fb0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
32fc0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
32fd0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
32fe0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 .**.** ^Register
32ff0 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 ing a NULL funct
33000 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 ion disables the
33010 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
33020 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 ^When the commi
33030 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 t hook callback
33040 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
33050 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 zero, the [COMMI
33060 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 T].** operation
33070 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f is allowed to co
33080 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e ntinue normally.
33090 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 ^If the commit
330a0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 hook.** returns
330b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
330c0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 the [COMMIT] is
330d0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
330e0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 [ROLLBACK]..**
330f0 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f ^The rollback ho
33100 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e ok is invoked on
33110 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 a rollback that
33120 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 results from a
33130 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 commit.** hook r
33140 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 eturning non-zer
33150 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f o, just as it wo
33160 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 uld be with any
33170 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a other rollback..
33180 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
33190 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
331a0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 API, a transacti
331b0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 on is said to ha
331c0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 ve been.** rolle
331d0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
331e0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
331f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
33200 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
33210 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
33220 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
33230 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
33240 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 to occur..** ^T
33250 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c he rollback call
33260 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f back is not invo
33270 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 ked if a transac
33280 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d tion is.** autom
33290 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
332a0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 back because the
332b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
332c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a tion is closed..
332d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
332e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 he [sqlite3_upda
332f0 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 te_hook()] inter
33300 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 face..*/.void *s
33310 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
33320 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ok(sqlite3*, int
33330 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
33340 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 *);.void *sqlite
33350 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
33360 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
33370 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a )(void *), void*
33380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33390 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 EF: Data Change
333a0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c Notification Cal
333b0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
333c0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 e sqlite3_update
333d0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
333e0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
333f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
33400 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ** with the [dat
33410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
33420 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 ] identified by
33430 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
33440 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f nt.** to be invo
33450 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 ked whenever a r
33460 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
33470 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
33480 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c ed..** ^Any call
33490 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
334a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 evious call to t
334b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
334c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 for the same dat
334d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
334e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a is overridden..
334f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
33500 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
33510 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 pointer to the f
33520 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b unction to invok
33530 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 e when a.** row
33540 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
33550 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
33560 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
33570 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
33580 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
33590 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 y of the third a
335a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
335b0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
335c0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 k()..** ^The sec
335d0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 ond callback arg
335e0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
335f0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c [SQLITE_INSERT],
33600 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
33610 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
33620 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 UPDATE], dependi
33630 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 ng on the operat
33640 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 ion that caused
33650 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
33660 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a to be invoked..*
33670 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 * ^The third and
33680 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
33690 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
336a0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
336b0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
336c0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
336d0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
336e0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
336f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 ..** ^The final
33700 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 callback paramet
33710 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 er is the [rowid
33720 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a ] of the row..**
33730 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 ^In the case of
33740 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 an update, this
33750 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 is the [rowid]
33760 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 after the update
33770 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a takes place..**
33780 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 .** ^(The update
33790 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 hook is not inv
337a0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e oked when intern
337b0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 al system tables
337c0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 are.** modified
337d0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 (i.e. sqlite_ma
337e0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f ster and sqlite_
337f0 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a sequence).)^.**.
33800 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 ** ^In the curre
33810 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
33820 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f n, the update ho
33830 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 ok.** is not inv
33840 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 oked when duplic
33850 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 ation rows are d
33860 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f eleted because o
33870 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 f an.** [ON CONF
33880 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 LICT | ON CONFLI
33890 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 CT REPLACE] clau
338a0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 se. ^Nor is the
338b0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 update hook.**
338c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 invoked when row
338d0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 s are deleted us
338e0 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 ing the [truncat
338f0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e e optimization].
33900 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f .** The exceptio
33910 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 ns defined in th
33920 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 is paragraph mig
33930 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ht change in a f
33940 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
33950 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
33960 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
33970 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e k implementation
33980 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
33990 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
339a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
339b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
339c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
339d0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 he update hook.
339e0 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 Any actions.**
339f0 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 to modify the da
33a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
33a10 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 n must be deferr
33a20 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ed until after t
33a30 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e he.** completion
33a40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
33a50 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 _step()] call th
33a60 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
33a70 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a update hook..**
33a80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
33a90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
33aa0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
33ab0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
33ac0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
33ad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
33ae0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
33af0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
33b00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
33b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
33b20 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
33b30 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a ,C,P) function.*
33b40 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 * returns the P
33b50 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 argument from th
33b60 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a e previous call.
33b70 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b ** on the same [
33b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33b90 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 ion] D, or NULL
33ba0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 for.** the first
33bb0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a call on D..**.*
33bc0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
33bd0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
33be0 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ook()] and [sqli
33bf0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
33c00 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 k()].** interfac
33c10 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c es..*/.void *sql
33c20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
33c30 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
33c40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c void(*)(void *,
33c50 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 int ,char const
33c60 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 *,char const *,s
33c70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 qlite3_int64),.
33c80 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*.);../*.**
33c90 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
33ca0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 e Or Disable Sha
33cb0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a red Pager Cache.
33cc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 ** KEYWORDS: {sh
33cd0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a ared cache}.**.*
33ce0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
33cf0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
33d00 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 bles the sharing
33d10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
33d20 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 cache.** and sc
33d30 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 hema data struct
33d40 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 ures between [da
33d50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
33d60 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d n | connections]
33d70 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
33d80 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e database. Sharin
33d90 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 g is enabled if
33da0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
33db0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 true.** and disa
33dc0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
33dd0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e ment is false.)^
33de0 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 .**.** ^Cache sh
33df0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 aring is enabled
33e00 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f and disabled fo
33e10 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 r an entire proc
33e20 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ess..** This is
33e30 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 a change as of S
33e40 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
33e50 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 5.0. In prior ve
33e60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
33e70 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 ,.** sharing was
33e80 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
33e90 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 bled for each th
33ea0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e read separately.
33eb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 .**.** ^(The cac
33ec0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 he sharing mode
33ed0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 set by this inte
33ee0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c rface effects al
33ef0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 l subsequent.**
33f00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
33f10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
33f20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
33f30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 and [sqlite3_ope
33f40 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 n16()]..** Exist
33f50 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e ing database con
33f60 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 nections continu
33f70 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e e use the sharin
33f80 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 g mode.** that w
33f90 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 as in effect at
33fa0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 the time they we
33fb0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a re opened.)^.**.
33fc0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e ** ^(This routin
33fd0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
33fe0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 E_OK] if shared
33ff0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 cache was enable
34000 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a d or disabled.**
34010 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
34020 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 An [error code]
34030 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 is returned othe
34040 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rwise.)^.**.** ^
34050 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 Shared cache is
34060 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
34070 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 ult. But this mi
34080 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ght change in.**
34090 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
340a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 of SQLite. App
340b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 lications that c
340c0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 are about shared
340d0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e .** cache settin
340e0 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 g should set it
340f0 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a explicitly..**.*
34100 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 * See Also: [SQ
34110 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 Lite Shared-Cach
34120 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 e Mode].*/.int s
34130 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
34140 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b ared_cache(int);
34150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34160 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 : Attempt To Fre
34170 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a e Heap Memory.**
34180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34190 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
341a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
341b0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 mpts to free N b
341c0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 ytes.** of heap
341d0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f memory by deallo
341e0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e cating non-essen
341f0 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f tial memory allo
34200 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 cations.** held
34210 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 by the database
34220 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 library. Memor
34230 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 y used to cache
34240 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 database.** page
34250 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
34260 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 formance is an e
34270 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 xample of non-es
34280 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a sential memory..
34290 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 ** ^sqlite3_rele
342a0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 ase_memory() ret
342b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
342c0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c of bytes actuall
342d0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 y freed,.** whic
342e0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 h might be more
342f0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 or less than the
34300 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 amount requeste
34310 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
34320 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
34330 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 y() routine is a
34340 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 no-op returning
34350 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 zero.** if SQLi
34360 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c te is not compil
34370 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
34380 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 ENABLE_MEMORY_MA
34390 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e NAGEMENT]..*/.in
343a0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 t sqlite3_releas
343b0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a e_memory(int);..
343c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
343d0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f Impose A Limit O
343e0 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a n Heap Size.**.*
343f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
34400 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
34410 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
34420 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 s and/or queries
34430 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d the.** soft lim
34440 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 it on the amount
34450 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 of heap memory
34460 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f that may be allo
34470 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e cated by SQLite.
34480 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 .** ^SQLite stri
34490 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 ves to keep heap
344a0 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 memory utilizat
344b0 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f ion below the so
344c0 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 ft heap.** limit
344d0 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 by reducing the
344e0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
344f0 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 held in the pag
34500 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 e cache.** as he
34510 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 ap memory usages
34520 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 approaches the
34530 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 limit..** ^The s
34540 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
34550 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 s "soft" because
34560 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c even though SQL
34570 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 ite strives to s
34580 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 tay.** below the
34590 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 limit, it will
345a0 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 exceed the limit
345b0 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e rather than gen
345c0 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c erate.** an [SQL
345d0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 ITE_NOMEM] error
345e0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
345f0 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 s, the soft heap
34600 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 limit .** is ad
34610 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a visory only..**.
34620 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 ** ^The return v
34630 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
34640 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
34650 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a t64() is the siz
34660 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 e of.** the soft
34670 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f heap limit prio
34680 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 r to the call.
34690 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 ^If the argument
346a0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a N is negative.*
346b0 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 * then no change
346c0 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 is made to the
346d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e soft heap limit.
346e0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 Hence, the cur
346f0 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 rent.** size of
34700 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
34710 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 mit can be deter
34720 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e mined by invokin
34730 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 g.** sqlite3_sof
34740 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
34750 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 with a negative
34760 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
34770 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e ^If the argumen
34780 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e t N is zero then
34790 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
347a0 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 imit is disabled
347b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f ..**.** ^(The so
347c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
347d0 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e not enforced in
347e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 the current imp
347f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 lementation.** i
34800 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 f one or more of
34810 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 following condi
34820 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a tions are true:.
34830 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
34840 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 i> The soft heap
34850 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f limit is set to
34860 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d zero..** <li> M
34870 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 emory accounting
34880 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 is disabled usi
34890 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e ng a combination
348a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
348b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
348c0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
348d0 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 MEMSTATUS],...)
348e0 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f start-time optio
348f0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 n and.** th
34900 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c e [SQLITE_DEFAUL
34910 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d T_MEMSTATUS] com
34920 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
34930 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 ..** <li> An alt
34940 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 ernative page ca
34950 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
34960 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 on is specified
34970 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 using.** [s
34980 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
34990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
349a0 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c ACHE],...)..** <
349b0 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 li> The page cac
349c0 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f he allocates fro
349d0 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 m its own memory
349e0 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a pool supplied.*
349f0 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 * by [sqlit
34a00 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
34a10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
34a20 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 CHE],...) rather
34a30 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 than.** fr
34a40 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 om the heap..**
34a50 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 </ul>)^.**.** Be
34a60 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c ginning with SQL
34a70 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
34a80 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 3, the soft heap
34a90 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 limit is enforc
34aa0 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 ed.** regardless
34ab0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
34ac0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 ot the [SQLITE_E
34ad0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e NABLE_MEMORY_MAN
34ae0 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 AGEMENT].** comp
34af0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
34b00 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 is invoked. Wit
34b10 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 h [SQLITE_ENABLE
34b20 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 _MEMORY_MANAGEME
34b30 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 NT],.** the soft
34b40 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 heap limit is e
34b50 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 nforced on every
34b60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
34b70 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 on. Without.**
34b80 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
34b90 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 EMORY_MANAGEMENT
34ba0 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 ], the soft heap
34bb0 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 limit is only e
34bc0 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 nforced.** when
34bd0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 memory is alloca
34be0 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 ted by the page
34bf0 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 cache. Testing
34c00 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 suggests that be
34c10 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 cause.** the pag
34c20 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 e cache is the p
34c30 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 redominate memor
34c40 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 y user in SQLite
34c50 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 , most.** applic
34c60 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 ations will achi
34c70 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 eve adequate sof
34c80 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 t heap limit enf
34c90 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 orcement without
34ca0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b .** the use of [
34cb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
34cc0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d MORY_MANAGEMENT]
34cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 ..**.** The circ
34ce0 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 umstances under
34cf0 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c which SQLite wil
34d00 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f l enforce the so
34d10 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 ft heap limit ma
34d20 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 y.** changes in
34d30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
34d40 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 of SQLite..*/.sq
34d50 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
34d60 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
34d70 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e mit64(sqlite3_in
34d80 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t64 N);../*.** C
34d90 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
34da0 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 ted Soft Heap Li
34db0 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a mit Interface.**
34dc0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
34dd0 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 * This is a depr
34de0 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f ecated version o
34df0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
34e00 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
34e10 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
34e20 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
34e30 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 is provided for
34e40 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
34e50 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 tibility.** only
34e60 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 . All new appli
34e70 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 cations should u
34e80 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 se the.** [sqlit
34e90 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
34ea0 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 it64()] interfac
34eb0 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 e rather than th
34ec0 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 is one..*/.SQLIT
34ed0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
34ee0 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 d sqlite3_soft_h
34ef0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 eap_limit(int N)
34f00 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
34f10 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 EF: Extract Meta
34f20 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c data About A Col
34f30 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a umn Of A Table.*
34f40 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
34f50 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 ne returns metad
34f60 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 ata about a spec
34f70 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 ific column of a
34f80 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 specific.** dat
34f90 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 abase table acce
34fa0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 ssible using the
34fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
34fc0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a ction] handle.**
34fd0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
34fe0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 irst function ar
34ff0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
35000 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 he column is ide
35010 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ntified by the s
35020 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 econd, third and
35030 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
35040 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 rs to.** this fu
35050 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 nction. ^The sec
35060 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
35070 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 either the name
35080 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
35090 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 .** (i.e. "main"
350a0 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 , "temp", or an
350b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
350c0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 e) containing th
350d0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 e specified.** t
350e0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 able or NULL. ^I
350f0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 f it is NULL, th
35100 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 en all attached
35110 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 databases are se
35120 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 arched.** for th
35130 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 e table using th
35140 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d e same algorithm
35150 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 used by the dat
35160 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a abase engine to.
35170 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 ** resolve unqua
35180 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 lified table ref
35190 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e erences..**.** ^
351a0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
351b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
351c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
351d0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 are the table a
351e0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d nd column.** nam
351f0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 e of the desired
35200 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 column, respect
35210 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f ively. Neither o
35220 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 f these paramete
35230 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rs.** may be NUL
35240 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 L..**.** ^Metada
35250 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 ta is returned b
35260 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 y writing to the
35270 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e memory location
35280 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
35290 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 5th.** and subse
352a0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 quent parameters
352b0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
352c0 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 n. ^Any of these
352d0 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 arguments may b
352e0 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 e.** NULL, in wh
352f0 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 ich case the cor
35300 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 responding eleme
35310 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 nt of metadata i
35320 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a s omitted..**.**
35330 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ^(<blockquote>.
35340 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
35350 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
35360 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e > Parameter <th>
35370 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 Output<br>Type
35380 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f <th> Descriptio
35390 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
353a0 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 5th <td> const
353b0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 char* <td> Data
353c0 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e type.** <tr><td>
353d0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 6th <td> const
353e0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 char* <td> Name
353f0 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 of default colla
35400 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a tion sequence.**
35410 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 <tr><td> 7th <t
35420 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
35430 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
35440 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c mn has a NOT NUL
35450 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 L constraint.**
35460 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 <tr><td> 8th <td
35470 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
35480 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
35490 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 n is part of the
354a0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 PRIMARY KEY.**
354b0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 <tr><td> 9th <td
354c0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
354d0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
354e0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d n is [AUTOINCREM
354f0 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ENT].** </table>
35500 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
35510 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d >)^.**.** ^The m
35520 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f emory pointed to
35530 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 by the characte
35540 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 r pointers retur
35550 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 ned for the.** d
35560 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 eclaration type
35570 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 and collation se
35580 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 quence is valid
35590 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e only until the n
355a0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 ext.** call to a
355b0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 ny SQLite API fu
355c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 nction..**.** ^I
355d0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 f the specified
355e0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c table is actuall
355f0 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 y a view, an [er
35600 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
35610 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 urned..**.** ^If
35620 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
35630 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 olumn is "rowid"
35640 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 , "oid" or "_row
35650 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b id_" and an.** [
35660 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
35670 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 KEY] column has
35680 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 been explicitly
35690 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 declared, then t
356a0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 he output.** par
356b0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 ameters are set
356c0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 for the explicit
356d0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
356e0 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 mn. ^(If there i
356f0 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 s no.** explicit
35700 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 ly declared [INT
35710 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
35720 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 ] column, then t
35730 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 he output.** par
35740 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 ameters are set
35750 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
35760 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 * <pre>.** d
35770 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 ata type: "INTEG
35780 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 ER".** colla
35790 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 tion sequence: "
357a0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e BINARY".** n
357b0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 ot null: 0.**
357c0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 primary key: 1
357d0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 .** auto inc
357e0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 rement: 0.** </p
357f0 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 re>)^.**.** ^(Th
35800 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 is function may
35810 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 load one or more
35820 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 schemas from da
35830 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 tabase files. If
35840 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 an.** error occ
35850 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 urs during this
35860 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 process, or if t
35870 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 he requested tab
35880 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 le or column.**
35890 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c cannot be found,
358a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
358b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
358c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
358d0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 e left.** in the
358e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
358f0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 ction] (to be re
35900 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 trieved using sq
35910 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e lite3_errmsg()).
35920 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 )^.**.** ^This A
35930 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c PI is only avail
35940 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
35950 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
35960 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
35970 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
35980 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
35990 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
359a0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 ol defined..*/.i
359b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 nt sqlite3_table
359c0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 _column_metadata
359d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
359e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
359f0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 /* Connection ha
35a00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
35a10 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 char *zDbName,
35a20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
35a30 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a e name or NULL *
35a40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
35a50 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 zTableName,
35a60 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f /* Table name */
35a70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
35a80 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f ColumnName, /
35a90 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f * Column name */
35aa0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a . char const **
35ab0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f pzDataType, /
35ac0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 * OUTPUT: Declar
35ad0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a ed data type */.
35ae0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
35af0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a zCollSeq, /*
35b00 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 OUTPUT: Collati
35b10 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 on sequence name
35b20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e */. int *pNotN
35b30 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 ull,
35b40 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
35b50 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f e if NOT NULL co
35b60 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 nstraint exists
35b70 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 */. int *pPrima
35b80 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 ryKey,
35b90 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
35ba0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 if column part
35bb0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a of PK */. int *
35bc0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 pAutoinc
35bd0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
35be0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e : True if column
35bf0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 is auto-increme
35c00 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nt */.);../*.**
35c10 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 CAPI3REF: Load A
35c20 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a n Extension.**.*
35c30 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
35c40 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 e loads an SQLit
35c50 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 e extension libr
35c60 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d ary from the nam
35c70 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ed file..**.** ^
35c80 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
35c90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
35ca0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
35cb0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 to load an.** SQ
35cc0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c Lite extension l
35cd0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 ibrary contained
35ce0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 in the file zFi
35cf0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 le..**.** ^The e
35d00 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 ntry point is zP
35d10 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d roc..** ^zProc m
35d20 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 ay be 0, in whic
35d30 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 h case the name
35d40 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 of the entry poi
35d50 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 nt.** defaults t
35d60 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e o "sqlite3_exten
35d70 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e sion_init"..** ^
35d80 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 The sqlite3_load
35d90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 _extension() int
35da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
35db0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e * [SQLITE_OK] on
35dc0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 success and [SQ
35dd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 LITE_ERROR] if s
35de0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 omething goes wr
35df0 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 ong..** ^If an e
35e00 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 rror occurs and
35e10 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 pzErrMsg is not
35e20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 0, then the.** [
35e30 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
35e40 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 ension()] interf
35e50 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 ace shall attemp
35e60 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a t to.** fill *pz
35e70 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f ErrMsg with erro
35e80 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 r message text s
35e90 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a tored in memory.
35ea0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ** obtained from
35eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
35ec0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 ()]. The calling
35ed0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f function.** sho
35ee0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 uld free this me
35ef0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 mory by calling
35f00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
35f10 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 ..**.** ^Extensi
35f20 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 on loading must
35f30 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 be enabled using
35f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 .** [sqlite3_ena
35f50 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
35f60 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 on()] prior to c
35f70 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c alling this API,
35f80 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
35f90 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 error will be r
35fa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 eturned..**.** S
35fb0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 ee also the [loa
35fc0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 d_extension() SQ
35fd0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a L function]..*/.
35fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 int sqlite3_load
35ff0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 _extension(. sq
36000 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
36010 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 /* Load the
36020 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 extension into t
36030 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e his database con
36040 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e nection */. con
36050 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 st char *zFile,
36060 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
36070 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 e shared library
36080 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 containing exte
36090 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 nsion */. const
360a0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 char *zProc,
360b0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e /* Entry point.
360c0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a Derived from z
360d0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 File if 0 */. c
360e0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 har **pzErrMsg
360f0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f /* Put erro
36100 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 r message here i
36110 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f f not 0 */.);../
36120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
36130 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 nable Or Disable
36140 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 Extension Loadi
36150 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 ng.**.** ^So as
36160 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 not to open secu
36170 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c rity holes in ol
36180 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 der applications
36190 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 that are.** unp
361a0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 repared to deal
361b0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c with extension l
361c0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 oading, and as a
361d0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c means of disabl
361e0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e ing.** extension
361f0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 loading while e
36200 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 valuating user-e
36210 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 ntered SQL, the
36220 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a following API.**
36230 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 is provided to
36240 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 turn the [sqlite
36250 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
36260 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e ()] mechanism on
36270 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 and off..**.**
36280 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 ^Extension loadi
36290 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 ng is off by def
362a0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 ault. See ticket
362b0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c #1863..** ^Call
362c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 the sqlite3_ena
362d0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
362e0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 on() routine wit
362f0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f h onoff==1.** to
36300 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 turn extension
36310 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 loading on and c
36320 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 all it with onof
36330 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 f==0 to turn.**
36340 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 it back off agai
36350 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 n..*/.int sqlite
36360 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
36370 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 tension(sqlite3
36380 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b *db, int onoff);
36390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
363a0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 : Automatically
363b0 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 Load Statically
363c0 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e Linked Extension
363d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e s.**.** ^This in
363e0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
363f0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 he xEntryPoint()
36400 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36410 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 invoked for.** e
36420 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 ach new [databas
36430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
36440 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 at is created.
36450 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 The idea here is
36460 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 that.** xEntryP
36470 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e oint() is the en
36480 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 try point for a
36490 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 statically linke
364a0 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 d SQLite extensi
364b0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f on.** that is to
364c0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
364d0 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c y loaded into al
364e0 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 l new database c
364f0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a onnections..**.*
36500 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 * ^(Even though
36510 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f the function pro
36520 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 totype shows tha
36530 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 t xEntryPoint()
36540 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 takes.** no argu
36550 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e ments and return
36560 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 s void, SQLite i
36570 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 nvokes xEntryPoi
36580 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a nt() with three.
36590 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 ** arguments and
365a0 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 expects and int
365b0 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 eger result as i
365c0 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 f the signature
365d0 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 of the.** entry
365e0 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 point where as f
365f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
36600 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
36610 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 ** int x
36620 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 EntryPoint(.** &
36630 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 nbsp; sqlite3
36640 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 *db,.**
36650 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a const char **
36660 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 pzErrMsg,.** &nb
36670 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 sp; const str
36680 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f uct sqlite3_api_
36690 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b routines *pThunk
366a0 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a .** );.*
366b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
366c0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 uote>)^.**.** If
366d0 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 the xEntryPoint
366e0 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 routine encount
366f0 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 ers an error, it
36700 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a should make *pz
36710 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 ErrMsg.** point
36720 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 to an appropriat
36730 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
36740 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b (obtained from [
36750 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
36760 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 )]).** and retur
36770 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 n an appropriate
36780 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 [error code].
36790 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 ^SQLite ensures
367a0 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a that *pzErrMsg.*
367b0 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 * is NULL before
367c0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e calling the xEn
367d0 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 tryPoint(). ^SQ
367e0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
367f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
36800 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 e()] on *pzErrMs
36810 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f g after xEntryPo
36820 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 int() returns.
36830 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 ^If any.** xEntr
36840 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 yPoint() returns
36850 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b an error, the [
36860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
36870 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
36880 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
36890 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 te3_open_v2()] c
368a0 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 all that provoke
368b0 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e d the xEntryPoin
368c0 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a t() will fail..*
368d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 *.** ^Calling sq
368e0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
368f0 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 sion(X) with an
36900 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 entry point X th
36910 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a at is already.**
36920 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 on the list of
36930 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 automatic extens
36940 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 ions is a harmle
36950 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e ss no-op. ^No en
36960 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c try point.** wil
36970 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 l be called more
36980 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 than once for e
36990 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
369a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 nection that is
369b0 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 opened..**.** Se
369c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
369d0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 _reset_auto_exte
369e0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 nsion()]..*/.int
369f0 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 sqlite3_auto_ex
36a00 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 tension(void (*x
36a10 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 EntryPoint)(void
36a20 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ));../*.** CAPI3
36a30 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d REF: Reset Autom
36a40 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c atic Extension L
36a50 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 oading.**.** ^Th
36a60 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 is interface dis
36a70 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 ables all automa
36a80 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 tic extensions p
36a90 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 reviously.** reg
36aa0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 istered using [s
36ab0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
36ac0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 nsion()]..*/.voi
36ad0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f d sqlite3_reset_
36ae0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 auto_extension(v
36af0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 oid);../*.** The
36b00 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 interface to th
36b10 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
36b20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 mechanism is cur
36b30 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
36b40 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
36b50 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
36b60 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
36b70 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
36b80 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
36b90 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
36ba0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
36bb0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
36bc0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
36bd0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
36be0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
36bf0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
36c00 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
36c10 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
36c20 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
36c30 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
36c40 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
36c50 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
36c60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 */../*.** Struct
36c70 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 ures used by the
36c80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
36c90 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 nterface.*/.type
36ca0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
36cb0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f e3_vtab sqlite3_
36cc0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 vtab;.typedef st
36cd0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
36ce0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f ex_info sqlite3_
36cf0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 index_info;.type
36d00 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
36d10 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 e3_vtab_cursor s
36d20 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
36d30 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 or;.typedef stru
36d40 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c ct sqlite3_modul
36d50 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 e sqlite3_module
36d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36d70 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
36d80 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
36d90 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 RDS: sqlite3_mod
36da0 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 ule {virtual tab
36db0 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a le module}.**.**
36dc0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c This structure,
36dd0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 sometimes calle
36de0 64 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 d a "virtual tab
36df0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
36e00 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
36e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
36e20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
36e30 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
36e40 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
36e50 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
36e60 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
36e70 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 .**.** ^A virtua
36e80 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 l table module i
36e90 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c s created by fil
36ea0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 ling in a persis
36eb0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 tent.** instance
36ec0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
36ed0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 re and passing a
36ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
36ef0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 instance.** to
36f00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36f10 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 module()] or [sq
36f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
36f30 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 ule_v2()]..** ^T
36f40 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 he registration
36f50 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e remains valid un
36f60 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 til it is replac
36f70 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e ed by a differen
36f80 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 t.** module or u
36f90 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 ntil the [databa
36fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
36fb0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 loses. The cont
36fc0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 ent.** of this s
36fd0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f tructure must no
36fe0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 t change while i
36ff0 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 t is registered
37000 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 with.** any data
37010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
37020 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
37030 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
37040 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
37050 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
37060 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
37070 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
37080 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
37090 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
370a0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
370b0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
370c0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
370d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
370e0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
370f0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
37100 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
37110 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
37120 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
37130 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
37140 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
37150 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
37160 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
37170 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
37180 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
37190 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
371a0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
371b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
371c0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
371d0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
371e0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
371f0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
37200 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
37210 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
37220 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
37230 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
37240 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
37250 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
37260 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
37270 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
37280 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
37290 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
372a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
372b0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
372c0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
372d0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
372e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
372f0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
37300 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
37310 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
37320 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
37330 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
37340 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
37350 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
37360 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
37370 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
37380 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
37390 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
373a0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
373b0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
373c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
373d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
373e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
373f0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
37400 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
37410 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
37420 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
37430 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
37440 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
37450 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
37460 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
37470 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
37480 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
37490 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
374a0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
374b0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
374c0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
374d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
374e0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
374f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
37500 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
37510 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
37520 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
37530 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 **ppArg);. int
37540 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
37550 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
37560 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
37570 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 w);. /* The met
37580 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
37590 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
375a0 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 he sqlite_module
375b0 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a object. Those .
375c0 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 ** below are f
375d0 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 or version 2 and
375e0 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 greater. */. i
375f0 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 nt (*xSavepoint)
37600 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
37610 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e VTab, int);. in
37620 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 t (*xRelease)(sq
37630 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
37640 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 b, int);. int (
37650 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 *xRollbackTo)(sq
37660 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
37670 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a b, int);.};../*.
37680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
37690 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 tual Table Index
376a0 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a ing Information.
376b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
376c0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
376d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
376e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
376f0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
37700 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
37710 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 used as part.**
37720 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
37730 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 table] interface
37740 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f to.** pass info
37750 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 rmation into and
37760 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 receive the rep
37770 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 ly from the [xBe
37780 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 stIndex].** meth
37790 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c od of a [virtual
377a0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
377b0 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 The fields unde
377c0 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 r **Inputs** are
377d0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 the.** inputs t
377e0 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 o xBestIndex and
377f0 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 are read-only.
37800 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 xBestIndex inse
37810 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c rts its.** resul
37820 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 ts into the **Ou
37830 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a tputs** fields..
37840 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e **.** ^(The aCon
37850 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
37860 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
37870 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
37880 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
37890 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
378a0 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
378b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
378c0 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c * where OP is =,
378d0 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 <, <=, &g
378e0 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 t;, or >=.)^
378f0 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 ^(The particula
37900 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
37910 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
37920 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e traint[].op usin
37930 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 g one of the.**
37940 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f [SQLITE_INDEX_CO
37950 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 NSTRAINT_EQ | SQ
37960 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
37970 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 RAINT_ values].)
37980 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 ^.** ^(The index
37990 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
379a0 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 s stored in.** a
379b0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f Constraint[].iCo
379c0 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 lumn.)^ ^(aCons
379d0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
379e0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
379f0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
37a00 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
37a10 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
37a20 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
37a30 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
37a40 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
37a50 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a if it cannot.)^.
37a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d **.** ^The optim
37a70 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
37a80 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
37a90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
37aa0 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
37ab0 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
37ac0 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
37ad0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
37ae0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
37af0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
37b00 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
37b10 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
37b20 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
37b30 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
37b40 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 * ^The aConstrai
37b50 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 nt[] array only
37b60 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c reports WHERE cl
37b70 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 ause terms that
37b80 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 are.** relevant
37b90 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 to the particula
37ba0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
37bb0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a being queried..*
37bc0 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f *.** ^Informatio
37bd0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
37be0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
37bf0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
37c00 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 y[]..** ^Each te
37c10 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 rm of aOrderBy r
37c20 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 ecords a column
37c30 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 of the ORDER BY
37c40 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 clause..**.** Th
37c50 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d e [xBestIndex] m
37c60 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
37c70 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
37c80 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
37c90 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
37ca0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
37cb0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
37cc0 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e ^If argvIndex>
37cd0 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 0 then.** the ri
37ce0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 ght-hand side of
37cf0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
37d00 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ng aConstraint[]
37d10 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a is evaluated.**
37d20 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 and becomes the
37d30 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e argvIndex-th en
37d40 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 try in argv. ^(
37d50 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 If aConstraintUs
37d60 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 age[].omit.** is
37d70 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 true, then the
37d80 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 constraint is as
37d90 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c sumed to be full
37da0 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 y handled by the
37db0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c .** virtual tabl
37dc0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 e and is not che
37dd0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 cked again by SQ
37de0 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 Lite.)^.**.** ^T
37df0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 he idxNum and id
37e00 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 xPtr values are
37e10 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 recorded and pas
37e20 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 sed into the.**
37e30 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 [xFilter] method
37e40 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 ..** ^[sqlite3_f
37e50 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 ree()] is used t
37e60 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 o free idxPtr if
37e70 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
37e80 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 needToFreeIdxPtr
37e90 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 is true..**.**
37ea0 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 ^The orderByCons
37eb0 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 umed means that
37ec0 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 output from [xFi
37ed0 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 lter]/[xNext] wi
37ee0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 ll occur in.** t
37ef0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 he correct order
37f00 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 to satisfy the
37f10 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
37f20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 so that no separ
37f30 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 ate.** sorting s
37f40 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e tep is required.
37f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 .**.** ^The esti
37f60 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 matedCost value
37f70 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f is an estimate o
37f80 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f f the cost of do
37f90 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 ing the.** parti
37fa0 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 cular lookup. A
37fb0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 full scan of a
37fc0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 table with N ent
37fd0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
37fe0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e .** a cost of N.
37ff0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 A binary searc
38000 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 h of a table of
38010 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 N entries should
38020 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 have a.** cost
38030 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 of approximately
38040 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 log(N)..*/.stru
38050 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
38060 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 _info {. /* Inp
38070 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f uts */. int nCo
38080 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
38090 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
380a0 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e entries in aCon
380b0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 straint */. str
380c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
380d0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 x_constraint {.
380e0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
380f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
38100 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d Column on left-
38110 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e hand side of con
38120 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 straint */.
38130 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 unsigned char op
38140 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e ; /* Con
38150 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 straint operator
38160 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
38170 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 d char usable;
38180 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 /* True if th
38190 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 is constraint is
381a0 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 usable */.
381b0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b int iTermOffset;
381c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 /* Use
381d0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 d internally - x
381e0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 BestIndex should
381f0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a ignore */. } *
38200 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 aConstraint;
38210 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 /* Table
38220 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 of WHERE clause
38230 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a constraints */.
38240 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 int nOrderBy;
38250 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
38260 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 Number of terms
38270 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 in the ORDER BY
38280 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 clause */. stru
38290 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
382a0 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 _orderby {.
382b0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
382c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
382d0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 umn number */.
382e0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
382f0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
38300 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
38310 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
38320 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b /. } *aOrderBy;
38330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
38340 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 * The ORDER BY c
38350 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 lause */. /* Ou
38360 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 tputs */. struc
38370 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
38380 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 constraint_usage
38390 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 {. int argvI
383a0 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 ndex;
383b0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 /* if >0, constr
383c0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 aint is part of
383d0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 argv to xFilter
383e0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 */. unsigned
383f0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 char omit;
38400 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 /* Do not code a
38410 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 test for this c
38420 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d onstraint */. }
38430 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 *aConstraintUsa
38440 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d ge;. int idxNum
38450 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
38460 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 /* Number used
38470 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 to identify the
38480 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 index */. char
38490 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 *idxStr;
384a0 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c /* String,
384b0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e possibly obtain
384c0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
384d0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 malloc */. int
384e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 needToFreeIdxStr
384f0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 ; /* Free i
38500 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 dxStr using sqli
38510 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 te3_free() if tr
38520 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 ue */. int orde
38530 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 rByConsumed;
38540 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 /* True if ou
38550 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 tput is already
38560 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 ordered */. dou
38570 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 ble estimatedCos
38580 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d t; /* Estim
38590 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 ated cost of usi
385a0 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f ng this index */
385b0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
385c0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
385d0 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 le Constraint Op
385e0 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a erator Codes.**.
385f0 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 ** These macros
38600 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f defined the allo
38610 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 wed values for t
38620 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 he.** [sqlite3_i
38630 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 ndex_info].aCons
38640 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c traint[].op fiel
38650 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 d. Each value r
38660 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 epresents.** an
38670 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 operator that is
38680 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 part of a const
38690 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 raint term in th
386a0 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f e wHERE clause o
386b0 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 f.** a query tha
386c0 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 t uses a [virtua
386d0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 l table]..*/.#de
386e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
386f0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 X_CONSTRAINT_EQ
38700 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
38710 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
38720 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 AINT_GT 4.#de
38730 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
38740 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 X_CONSTRAINT_LE
38750 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
38760 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
38770 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 AINT_LT 16.#d
38780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
38790 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 EX_CONSTRAINT_GE
387a0 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 32.#define S
387b0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
387c0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a TRAINT_MATCH 64.
387d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
387e0 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 Register A Virt
387f0 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d ual Table Implem
38800 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e entation.**.** ^
38810 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
38820 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 re used to regis
38830 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 ter a new [virtu
38840 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
38850 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c name..** ^Modul
38860 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 e names must be
38870 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 registered befor
38880 65 0a 2