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 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 estructors. The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 r.** interfaces
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 hen the.** last
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 nt is finalized
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 finished. The
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 .** destructors
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 se | close] all
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 bject. ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 deprecated. It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rface.**.** The
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 .** ^If the 5th
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 rrors.** occur,
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 nter in its 5th
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 out running any
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 sult. ^The 3rd
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 n. ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 4th argument to
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 s where each.**
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 e()]..**.** ^If
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 .** to an empty
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 .** is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 n]..** <li> The
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 into.** th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 _on_conflict()]
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 15 /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 ne SQLITE_EMPTY
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 16 /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 tabase is empty
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 E_SCHEMA 17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 ITE_TOOBIG
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 18 /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 TRAINT 19 /*
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a USE 21 /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 S 22 /*
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 e SQLITE_AUTH
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 23 /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 ITE_FORMAT
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 24 /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 ne SQLITE_RANGE
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 25 /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 qlite3_bind out
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 B 26 /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 ile opened that
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 codes}.**.** In
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 eturn one of 26
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c odes]. However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 experience has
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 shown that many
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 like. In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 sult codes that
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 s. The extended
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 t codes will be
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ime. Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 hould expect.**
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 be extended. I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 TOPEN_NOTEMPDIR
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 ANTOPEN_ISDIR
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 TE_CORRUPT_VTAB
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c OVERY (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 ANTLOCK (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 LLBACK
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 (SQLITE_ABORT |
5760: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
5770: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5780: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 T_UNIQUE (
5790: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
57a0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 T | (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
57c0: 52 41 49 4e 54 5f 52 41 49 53 45 20 20 20 20 20 RAINT_RAISE
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
57e0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a RAINT | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5800: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 ONSTRAINT_FOREIG
5810: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 NKEY (SQLITE_C
5820: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c ONSTRAINT | (3<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5840: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 TE_CONSTRAINT_CH
5850: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 ECK (SQLI
5860: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5870: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5880: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5890: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 T_PRIMARYKEY (
58a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
58b0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 T | (5<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
58d0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 RAINT_NOTNULL
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
58f0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a RAINT | (6<<8)).
5900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5910: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 ONSTRAINT_COMMIT
5920: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 HOOK (SQLITE_C
5930: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c ONSTRAINT | (7<<
5940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5950: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 TE_CONSTRAINT_VT
5960: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 AB (SQLI
5970: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5980: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (8<<8)).#define
5990: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
59a0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 T_FUNCTION (
59b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
59c0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f 2a 0a T | (9<<8))../*.
59d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
59e0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
59f0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
5a00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
5a10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
5a20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
5a30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
5a40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5a50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5a60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5a70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5a80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
5a90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
5aa0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
5ab0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5ac0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5ad0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
5ae0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5af0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5b00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5b10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5b20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
5b30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5b40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5b50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5b60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5b70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
5b80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5b90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5ba0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5bb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5bc0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* VFS o
5bd0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5be0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5bf0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5c00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* VFS o
5c10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 QLITE_OPEN_AUTOP
5c30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
5c40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* VFS o
5c50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 QLITE_OPEN_URI
5c70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5c80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
5c90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5ca0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
5cc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
5cd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
5ce0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5cf0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5d00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5d10: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5d20: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* VFS o
5d30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5d40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5d50: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5d60: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
5d70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
5d90: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
5da0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* VFS o
5db0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5dd0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5de0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* VFS o
5df0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5e10: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
5e20: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* VFS o
5e30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
5e50: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
5e60: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* VFS o
5e70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5e80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
5e90: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
5ea0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* VFS o
5eb0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
5ed0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
5ee0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
5ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
5f20: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
5f30: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
5f40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5f50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
5f70: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
5f80: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
5fc0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
5fd0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
6010: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6020: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
6040: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
6050: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6060: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
6070: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
6080: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
6090: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
60a0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
60b0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
60c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
60d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
60e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
60f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
6100: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
6110: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
6120: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
6130: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6140: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
6150: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
6160: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
6170: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
6180: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
6190: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
61a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
61b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
61c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
61d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
61e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
61f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6200: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6210: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
6220: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
6230: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6240: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
6250: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
6260: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
6270: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
6280: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
6290: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
62a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
62b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
62c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
62d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
62e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
62f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6300: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6310: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
6320: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
6330: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6340: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
6350: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
6360: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6370: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
6380: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
6390: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
63a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
63b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
63c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
63d0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
63e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
63f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
6400: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6410: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
6420: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
6430: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6440: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
6450: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
6460: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
6470: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
6480: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
6490: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
64a0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
64b0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
64c0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
64d0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
64e0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
64f0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a e unchanged..*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6510: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
6520: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6530: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6550: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
6560: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6580: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
6590: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
65a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
65b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
65c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
65d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
65e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
65f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
6600: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6610: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
6620: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
6630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6640: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
6650: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6660: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
6670: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
6680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6690: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
66a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
66b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
66c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
66d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
66e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
66f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6700: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6710: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6720: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
6730: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6740: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
6750: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
6760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6770: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
6780: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
6790: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
67a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
67b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
67c0: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 0x00001000../*.*
67d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
67e0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
67f0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
6800: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
6810: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6820: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
6830: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
6840: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
6850: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
6860: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
6870: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
6880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6890: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
68a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
68b0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
68d0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
68e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
68f0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
6900: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
6910: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
6920: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
6930: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
6940: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
6950: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
6960: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
6970: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 e Flags.**.** Wh
6980: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 en SQLite invoke
6990: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 s the xSync() me
69a0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 thod of an.** [s
69b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
69c0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 s] object it use
69d0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 s a combination
69e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 of.** these inte
69f0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
6a00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
6a10: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
6a20: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
6a30: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
6a40: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
6a50: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
6a60: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
6a70: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
6a80: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
6a90: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
6aa0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
6ab0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 t be flushed. If
6ac0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
6ad0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 bits of the flag
6ae0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 .** equal SQLITE
6af0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 _SYNC_NORMAL, th
6b00: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 at means to use
6b10: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
6b20: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 emantics..** If
6b30: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
6b40: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 its equal SQLITE
6b50: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 _SYNC_FULL, that
6b60: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 means.** to use
6b70: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
6b80: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 fullsync instead
6b90: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a of fsync()..**.
6ba0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 ** Do not confus
6bb0: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e e the SQLITE_SYN
6bc0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
6bd0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
6be0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ags.** with the
6bf0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
6c00: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 ous]=NORMAL and
6c10: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
6c20: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 ous]=FULL.** set
6c30: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e tings. The [syn
6c40: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d chronous pragma]
6c50: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e determines when
6c60: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a calls to the.**
6c70: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f xSync VFS metho
6c80: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c d occur and appl
6c90: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 ies uniformly ac
6ca0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 ross all platfor
6cb0: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 ms..** The SQLIT
6cc0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e E_SYNC_NORMAL an
6cd0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 d SQLITE_SYNC_FU
6ce0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 LL flags determi
6cf0: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 ne how.** energe
6d00: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 tic or rigorous
6d10: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 or forceful the
6d20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 sync operations
6d30: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 are and.** only
6d40: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 make a differenc
6d50: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 e on Mac OSX for
6d60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c the default SQL
6d70: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 ite code..** (Th
6d80: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d ird-party VFS im
6d90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 plementations mi
6da0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 ght also make th
6db0: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a e distinction.**
6dc0: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f between SQLITE_
6dd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6de0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6df0: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a , but among the.
6e00: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ** operating sys
6e10: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 tems natively su
6e20: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
6e30: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a e, only Mac OSX.
6e40: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 ** cares about t
6e50: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a he difference.).
6e60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6e70: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 E_SYNC_NORMAL
6e80: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 0x00002.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
6ea0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 _FULL 0
6eb0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 x00003.#define S
6ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
6ed0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 NLY 0x00010
6ee0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6ef0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
6f00: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a pen File Handle.
6f10: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 **.** An [sqlite
6f20: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 3_file] object r
6f30: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
6f40: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a n file in the .*
6f50: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c * [sqlite3_vfs |
6f60: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
6f70: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 yer]. Individua
6f80: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a l OS interface.*
6f90: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
6fa0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
6fb0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
6fc0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
6fd0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
6fe0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ields.** for the
6ff0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 ir own use. The
7000: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 pMethods entry
7010: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
7020: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
7030: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
7040: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d t that defines m
7050: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f ethods for perfo
7060: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 rming.** I/O ope
7070: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f rations on the o
7080: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 pen file..*/.typ
7090: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
70a0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 te3_file sqlite3
70b0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 _file;.struct sq
70c0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 lite3_file {. c
70d0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 onst struct sqli
70e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a te3_io_methods *
70f0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 pMethods; /* Me
7100: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 thods for an ope
7110: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a n file */.};../*
7120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
7130: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 Interface File
7140: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 Virtual Methods
7150: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 Object.**.** Eve
7160: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
7170: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
7180: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
7190: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
71a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
71b0: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
71c0: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
71d0: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
71e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
71f0: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
7200: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
7210: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
7220: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
7230: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
7240: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
7250: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
7260: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
7270: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
7280: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
7290: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
72a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
72b0: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 .** If the [sqli
72c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d te3_vfs.xOpen] m
72d0: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 ethod sets the s
72e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
72f0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a hods element .**
7300: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 to a non-NULL p
7310: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 ointer, then the
7320: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7330: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f ods.xClose metho
7340: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f d.** may be invo
7350: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 ked even if the
7360: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7370: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 en] reported tha
7380: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 t it failed. Th
7390: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f e.** only way to
73a0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 prevent a call
73b0: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 to xClose follow
73c0: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 ing a failed [sq
73d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
73e0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b .** is for the [
73f0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7400: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 n] to set the sq
7410: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
7420: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 ods element.** t
7430: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 o NULL..**.** Th
7440: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
7450: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 to xSync may be
7460: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
7470: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a SYNC_NORMAL] or.
7480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f ** [SQLITE_SYNC_
7490: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 FULL]. The firs
74a0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 t choice is the
74b0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a normal fsync()..
74c0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 ** The second ch
74d0: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 oice is a Mac OS
74e0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e X style fullsyn
74f0: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f c. The [SQLITE_
7500: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a SYNC_DATAONLY].*
7510: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 * flag may be OR
7520: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 ed in to indicat
7530: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 e that only the
7540: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 data of the file
7550: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 .** and not its
7560: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 inode needs to b
7570: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 e synced..**.**
7580: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 The integer valu
7590: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e es to xLock() an
75a0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 d xUnlock() are
75b0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a one of.** <ul>.*
75c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
75d0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c OCK_NONE],.** <l
75e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
75f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SHARED],.** <li>
7600: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
7610: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SERVED],.** <li>
7620: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
7630: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c NDING], or.** <l
7640: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7650: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c EXCLUSIVE]..** <
7660: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 /ul>.** xLock()
7670: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f increases the lo
7680: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 ck. xUnlock() de
7690: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
76a0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 ..** The xCheckR
76b0: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 eservedLock() me
76c0: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 thod checks whet
76d0: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 her any database
76e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 connection,.**
76f0: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 either in this p
7700: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d rocess or in som
7710: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c e other process,
7720: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 is holding a RE
7730: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 SERVED,.** PENDI
7740: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 NG, or EXCLUSIVE
7750: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c lock on the fil
7760: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 e. It returns t
7770: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 rue.** if such a
7780: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 lock exists and
7790: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 false otherwise
77a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c ..**.** The xFil
77b0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f eControl() metho
77c0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 d is a generic i
77d0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c nterface that al
77e0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 lows custom.** V
77f0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7800: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 ns to directly c
7810: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 ontrol an open f
7820: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ile using the.**
7830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
7840: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
7850: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ace. The second
7860: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 "op" argument i
7870: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 s an.** integer
7880: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 opcode. The thi
7890: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 rd argument is a
78a0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 generic pointer
78b0: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 intended to.**
78c0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 point to a struc
78d0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f ture that may co
78e0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 ntain arguments
78f0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 or space in whic
7900: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 h to.** write re
7910: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f turn values. Po
7920: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 tential uses for
7930: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
7940: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 might be.** func
7950: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 tions to enable
7960: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 blocking locks w
7970: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f ith timeouts, to
7980: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c change the.** l
7990: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 ocking strategy
79a0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 (for example to
79b0: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 use dot-file loc
79c0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a ks), to inquire.
79d0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 ** about the sta
79e0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f tus of a lock, o
79f0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 r to break stale
7a00: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c locks. The SQL
7a10: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 ite.** core rese
7a20: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 rves all opcodes
7a30: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 less than 100 f
7a40: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a or its own use..
7a50: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e ** A [SQLITE_FCN
7a60: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c TL_LOCKSTATE | l
7a70: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 ist of opcodes]
7a80: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 less than 100 is
7a90: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 available..** A
7aa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
7ab0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d define a custom
7ac0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
7ad0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 thod should use
7ae0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 opcodes.** great
7af0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 er than 100 to a
7b00: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 void conflicts.
7b10: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
7b20: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 ions should.** r
7b30: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f eturn [SQLITE_NO
7b40: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 TFOUND] for file
7b50: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 control opcodes
7b60: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
7b70: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a t.** recognize..
7b80: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f **.** The xSecto
7b90: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 rSize() method r
7ba0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f eturns the secto
7bb0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a r size of the.**
7bc0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 device that und
7bd0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e erlies the file.
7be0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a The sector siz
7bf0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 e is the.** mini
7c00: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 mum write that c
7c10: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 an be performed
7c20: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 without disturbi
7c30: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 ng.** other byte
7c40: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 s in the file.
7c50: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
7c60: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 cteristics().**
7c70: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
7c80: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 bit vector desc
7c90: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 ribing behaviors
7ca0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 of the.** under
7cb0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a lying device:.**
7cc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7cd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
7ce0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b TOMIC].** <li> [
7cf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7d00: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC512].** <li>
7d10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7d20: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC1K].** <li>
7d30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7d40: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC2K].** <li>
7d50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7d60: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC4K].** <li>
7d70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7d80: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC8K].** <li>
7d90: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7da0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC16K].** <li>
7db0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
7dc0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC32K].** <li
7dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
7de0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c ATOMIC64K].** <l
7df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7e00: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a _SAFE_APPEND].**
7e10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7e20: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a CAP_SEQUENTIAL].
7e30: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
7e40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
7e50: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
7e60: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
7e70: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
7e80: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
7e90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
7ea0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
7eb0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
7ec0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
7ed0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
7ee0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
7ef0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
7f00: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
7f10: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
7f20: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
7f30: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
7f40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
7f50: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
7f60: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
7f70: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
7f80: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
7f90: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
7fa0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
7fb0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
7fc0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
7fd0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
7fe0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
7ff0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
8010: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
8020: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
8030: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
8040: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
8050: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
8060: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
8070: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 te()..**.** If x
8080: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 Read() returns S
8090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 QLITE_IOERR_SHOR
80a0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 T_READ it must a
80b0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 lso fill.** in t
80c0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f he unread portio
80d0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ns of the buffer
80e0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 with zeros. A
80f0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c VFS that.** fail
8100: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 s to zero-fill s
8110: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 hort reads might
8120: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 seem to work.
8130: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c However,.** fail
8140: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c ure to zero-fill
8150: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c short reads wil
8160: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 l eventually lea
8170: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 d to.** database
8180: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
8190: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
81a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
81b0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 s sqlite3_io_met
81c0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
81d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
81e0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
81f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
8200: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
8210: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 ;. int (*xRead)
8220: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8230: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c void*, int iAmt,
8240: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
8250: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
8260: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 Write)(sqlite3_f
8270: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ile*, const void
8280: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c *, int iAmt, sql
8290: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
82a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e );. int (*xTrun
82b0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 cate)(sqlite3_fi
82c0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
82d0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 64 size);. int
82e0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
82f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 _file*, int flag
8300: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c s);. int (*xFil
8310: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 eSize)(sqlite3_f
8320: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8330: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 t64 *pSize);. i
8340: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 nt (*xLock)(sqli
8350: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
8360: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b . int (*xUnlock
8370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8380: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
8390: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
83a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
83b0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
83c0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f . int (*xFileCo
83d0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 ntrol)(sqlite3_f
83e0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f ile*, int op, vo
83f0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 id *pArg);. int
8400: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 (*xSectorSize)(
8410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
8420: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 int (*xDeviceC
8430: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 haracteristics)(
8440: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
8450: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f /* Methods abo
8460: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 ve are valid for
8470: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 version 1 */.
8480: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 int (*xShmMap)(s
8490: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
84a0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c t iPg, int pgsz,
84b0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 int, void volat
84c0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a ile**);. int (*
84d0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 xShmLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 3_file*, int off
84f0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 set, int n, int
8500: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 flags);. void (
8510: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 *xShmBarrier)(sq
8520: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8530: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 int (*xShmUnmap)
8540: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8550: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b int deleteFlag);
8560: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8570: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8580: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 r version 2 */.
8590: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
85a0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
85b0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
85c0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
85d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
85e0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
85f0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a rol Opcodes.**.*
8600: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
8610: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 constants are op
8620: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 codes for the xF
8630: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
8640: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c d.** of the [sql
8650: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
8660: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 object and for
8670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
8680: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 e_control()].**
8690: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
86a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
86b0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 TL_LOCKSTATE] op
86c0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
86d0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
86e0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
86f0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
8700: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 rol method to wr
8710: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 ite the current
8720: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 state of.** the
8730: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 lock (one of [SQ
8740: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
8750: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
8760: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ARED],.** [SQLIT
8770: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
8780: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 , [SQLITE_LOCK_P
8790: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c ENDING], or [SQL
87a0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
87b0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 VE]).** into an
87c0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 integer that the
87d0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 pArg argument p
87e0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 oints to. This c
87f0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
8800: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
8810: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 ing and only nee
8820: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ds to be support
8830: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 ed when SQLITE_T
8840: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 EST.** is define
8850: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c d..** <ul>.** <l
8860: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
8870: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 _SIZE_HINT]].**
8880: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8890: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 L_SIZE_HINT] opc
88a0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 ode is used by S
88b0: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 QLite to give th
88c0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 e VFS.** layer a
88d0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 hint of how lar
88e0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
88f0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 file will grow t
8900: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a o be during the.
8910: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 ** current trans
8920: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 action. This hi
8930: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e nt is not guaran
8940: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 teed to be accur
8950: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 ate but it.** is
8960: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 often close. T
8970: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 he underlying VF
8980: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 S might choose t
8990: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 o preallocate da
89a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 tabase.** file s
89b0: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 pace based on th
89c0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 is hint in order
89d0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 to help writes
89e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
89f0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 ** file run fast
8a00: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b er..**.** <li>[[
8a10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
8a20: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 NK_SIZE]].** The
8a30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
8a40: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 HUNK_SIZE] opcod
8a50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 e is used to req
8a60: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 uest that the VF
8a70: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 S.** extends and
8a80: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 truncates the d
8a90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 atabase file in
8aa0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 chunks of a size
8ab0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
8ac0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 the user. The f
8ad0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
8ae0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f o [sqlite3_file_
8af0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c control()] shoul
8b00: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 d .** point to a
8b10: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 n integer (type
8b20: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 int) containing
8b30: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 the new chunk-si
8b40: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 ze to use.** for
8b50: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 the nominated d
8b60: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 atabase. Allocat
8b70: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c ing database fil
8b80: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 e space in large
8b90: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 .** chunks (say
8ba0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 1MB at a time),
8bb0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d may reduce file-
8bc0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 system fragmenta
8bd0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 tion and.** impr
8be0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ove performance
8bf0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e on some systems.
8c00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
8c10: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
8c20: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 OINTER]].** The
8c30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
8c40: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f LE_POINTER] opco
8c50: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
8c60: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
8c70: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
8c80: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
8c90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
8ca0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
8cb0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
8cc0: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 on. See the [sq
8cd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
8ce0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 ol()] documentat
8cf0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 ion for.** addit
8d00: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
8d10: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 n..**.** <li>[[S
8d20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
8d30: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 _OMITTED]].** ^(
8d40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8d50: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 L_SYNC_OMITTED]
8d60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
8d70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
8d80: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 y.** SQLite and
8d90: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 sent to all VFSe
8da0: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 s in place of a
8db0: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e call to the xSyn
8dc0: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e c method.** when
8dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
8de0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 nnection has [PR
8df0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
8e00: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a ] set to OFF.)^.
8e10: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 ** Some speciali
8e20: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 zed VFSes need t
8e30: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 his signal in or
8e40: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 der to operate c
8e50: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e orrectly.** when
8e60: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
8e70: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 nous | PRAGMA sy
8e80: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 nchronous=OFF] i
8e90: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 s set, but most
8ea0: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 .** VFSes do not
8eb0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
8ec0: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c l and should sil
8ed0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
8ee0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 s opcode..** App
8ef0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
8f00: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 not call [sqlit
8f10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8f20: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 )] with this.**
8f30: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 opcode as doing
8f40: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 so may disrupt t
8f50: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 he operation of
8f60: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
8f70: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f VFSes.** that do
8f80: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
8f90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
8fa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
8fb0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 _RETRY]].** ^The
8fc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
8fd0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f IN32_AV_RETRY] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
8ff0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d configure autom
9000: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f atic.** retry co
9010: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 unts and interva
9020: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 ls for certain d
9030: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f isk I/O operatio
9040: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 ns for the.** wi
9050: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f ndows [VFS] in o
9060: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
9070: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 robustness in th
9080: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a e presence of.**
9090: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 anti-virus prog
90a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c rams. By defaul
90b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 t, the windows V
90c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 FS will retry fi
90d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 le read,.** file
90e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 write, and file
90f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f delete operatio
9100: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 ns up to 10 time
9110: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a s, with a delay.
9120: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 ** of 25 millise
9130: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 conds before the
9140: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 first retry and
9150: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 with the delay
9160: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 increasing.** by
9170: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 an additional 2
9180: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 5 milliseconds w
9190: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 ith each subsequ
91a0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 ent retry. This
91b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 .** opcode allow
91c0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 s these two valu
91d0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 es (10 retries a
91e0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e nd 25 millisecon
91f0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 ds of delay).**
9200: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 to be adjusted.
9210: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 The values are
9220: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 changed for all
9230: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
9240: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 ions.** within t
9250: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e he same process.
9260: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 The argument i
9270: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
9280: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a n array of two.*
9290: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 * integers where
92a0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 the first integ
92b0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 er i the new ret
92c0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 ry count and the
92d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 second.** integ
92e0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e er is the delay.
92f0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 If either inte
9300: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c ger is negative,
9310: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e then the settin
9320: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e g.** is not chan
9330: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 ged but instead
9340: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
9350: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 of that setting
9360: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e is written.** in
9370: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 to the array ent
9380: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 ry, allowing the
9390: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 current retry s
93a0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a ettings to be.**
93b0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
93c0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 The zDbName para
93d0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 meter is ignored
93e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
93f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 LITE_FCNTL_PERSI
9400: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 ST_WAL]].** ^The
9410: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
9420: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f ERSIST_WAL] opco
9430: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
9440: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
9450: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 * persistent [WA
9460: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 L | Write Ahead
9470: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 Log] setting. B
9480: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 y default, the a
9490: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 uxiliary.** writ
94a0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 e ahead log and
94b0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
94c0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 les used for tra
94d0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
94e0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 .** are automati
94f0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 cally deleted wh
9500: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f en the latest co
9510: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 nnection to the
9520: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 database.** clos
9530: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 es. Setting per
9540: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
9550: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 causes those fi
9560: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 les to persist a
9570: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 fter.** close.
9580: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 Persisting the f
9590: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 iles is useful w
95a0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 hen other proces
95b0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a ses that do not.
95c0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 ** have write pe
95d0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 rmission on the
95e0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 directory contai
95f0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
9600: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 e file want.** t
9610: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 o read the datab
9620: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 ase file, as the
9630: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 WAL and shared
9640: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 memory files mus
9650: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 t exist.** in or
9660: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 der for the data
9670: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 base to be reada
9680: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 ble. The fourth
9690: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
96a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
96b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 ontrol()] for th
96c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 is opcode should
96d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
96e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 an integer..**
96f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 That integer is
9700: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 0 to disable per
9710: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
9720: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
9730: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 persistent.** WA
9740: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 L mode. If the
9750: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
9760: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
9770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
9780: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 urrent.** WAL pe
9790: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e rsistence settin
97a0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
97b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
97c0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
97d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
97e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 E_FCNTL_POWERSAF
97f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 E_OVERWRITE] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 ** persistent "p
9830: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 owersafe-overwri
9840: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 te" or "PSOW" se
9850: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 tting. The PSOW
9860: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 setting.** dete
9870: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 rmines the [SQLI
9880: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
9890: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 FE_OVERWRITE] bi
98a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 t of the.** xDev
98b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
98c0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 cs methods. The
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
9950: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d le zero-damage m
9960: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
9970: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a le zero-damage.*
9980: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 * mode. If the
9990: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
99a0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
99b0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
99c0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 urrent.** zero-d
99d0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 amage mode setti
99e0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
99f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
9a00: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
9a10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f [SQLITE_FCNTL_O
9a20: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
9a30: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 is invoked by S
9a40: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e QLite after open
9a50: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 ing.** a write t
9a60: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e ransaction to in
9a70: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c dicate that, unl
9a80: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 ess it is rolled
9a90: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a back for some.*
9aa0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e * reason, the en
9ab0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 tire database fi
9ac0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 le will be overw
9ad0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 ritten by the cu
9ae0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 rrent .** transa
9af0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 ction. This is u
9b00: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 sed by VACUUM op
9b10: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
9b20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9b30: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 TL_VFSNAME]].**
9b40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9b50: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f TL_VFSNAME] opco
9b60: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 de can be used t
9b70: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d o obtain the nam
9b80: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 es of.** all [VF
9b90: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 Ses] in the VFS
9ba0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 stack. The name
9bb0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 s are of all VFS
9bc0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a shims and the.*
9bd0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c * final bottom-l
9be0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 evel VFS are wri
9bf0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
9c00: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
9c10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
9c20: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 oc()] and the re
9c30: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 sult is stored i
9c40: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 n the char* vari
9c50: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 able.** that the
9c60: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
9c70: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 r of [sqlite3_fi
9c80: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f le_control()] po
9c90: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 ints to..** The
9ca0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e caller is respon
9cb0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e sible for freein
9cc0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 g the memory whe
9cd0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 n done. As with
9ce0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e .** all file-con
9cf0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 trol actions, th
9d00: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e ere is no guaran
9d10: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 tee that this wi
9d20: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 ll actually.** d
9d30: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c o anything. Cal
9d40: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 lers should init
9d50: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a ialize the char*
9d60: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e variable to a N
9d70: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ULL.** pointer i
9d80: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 n case this file
9d90: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 -control is not
9da0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 implemented. Th
9db0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a is file-control.
9dc0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 ** is intended f
9dd0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 or diagnostic us
9de0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c e only..**.** <l
9df0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9e00: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 _PRAGMA]].** ^Wh
9e10: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 enever a [PRAGMA
9e20: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 ] statement is p
9e30: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 arsed, an [SQLIT
9e40: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
9e50: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
9e60: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 is sent to the
9e70: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 open [sqlite3_fi
9e80: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 le] object corre
9e90: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 sponding.** to t
9ea0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9eb0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 to which the pr
9ec0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 agma statement r
9ed0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 efers. ^The argu
9ee0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
9ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
9f00: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
9f10: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 l is an array of
9f20: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
9f30: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 strings (char**)
9f40: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 in which the se
9f50: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 cond element of
9f60: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 the array.** is
9f70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
9f80: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 pragma and the t
9f90: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 hird element is
9fa0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 the argument to
9fb0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 the.** pragma or
9fc0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 NULL if the pra
9fd0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d gma has no argum
9fe0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ent. ^The handl
9ff0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 er for an.** [SQ
a000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
a010: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
a020: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d can optionally m
a030: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c ake the first el
a040: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 ement.** of the
a050: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 char** argument
a060: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
a070: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
a080: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
a090: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 ()].** or the eq
a0a0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 uivalent and tha
a0b0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 t string will be
a0c0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 come the result
a0d0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 of the pragma or
a0e0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 .** the error me
a0f0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 ssage if the pra
a100: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 gma fails. ^If t
a110: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
a120: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
a130: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
a140: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
a150: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 D], then normal
a160: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f .** [PRAGMA] pro
a170: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 cessing continue
a180: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c s. ^If the [SQL
a190: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a1a0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
a1b0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
a1c0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 E_OK], then the
a1d0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 parser assumes t
a1e0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 hat the.** VFS h
a1f0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 as handled the P
a200: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 RAGMA itself and
a210: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 the parser gene
a220: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a rates a no-op.**
a230: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
a240: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 ent. ^If the [S
a250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a260: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a270: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
a280: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 result code othe
a290: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
a2a0: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f K] or [SQLITE_NO
a2b0: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 TFOUND], that me
a2c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ans.** that the
a2d0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 VFS encountered
a2e0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 an error while h
a2f0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 andling the [PRA
a300: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 GMA] and the.**
a310: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 compilation of t
a320: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 he PRAGMA fails
a330: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
a340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
a350: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 TL_PRAGMA].** fi
a360: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 le control occur
a370: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 s at the beginni
a380: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 ng of pragma sta
a390: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 tement analysis
a3a0: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 and so.** it is
a3b0: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 able to override
a3c0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d built-in [PRAGM
a3d0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a A] statements..*
a3e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
a3f0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
a400: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 LER]].** ^This f
a410: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 ile-control may
a420: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 be invoked by SQ
a430: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 Lite on the data
a440: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 base file handle
a450: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 .** shortly afte
a460: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 r it is opened i
a470: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 n order to provi
a480: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 de a custom VFS
a490: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 with access.** t
a4a0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e o the connection
a4b0: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 s busy-handler c
a4c0: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 allback. The arg
a4d0: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 ument is of type
a4e0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 (void **).** -
a4f0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 an array of two
a500: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e (void *) values.
a510: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 The first (void
a520: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 *) actually poi
a530: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 nts.** to a func
a540: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e tion of type (in
a550: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 t (*)(void *)).
a560: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f In order to invo
a570: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ke the connectio
a580: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c ns.** busy-handl
a590: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f er, this functio
a5a0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f n should be invo
a5b0: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 ked with the sec
a5c0: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a ond (void *) in.
a5d0: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 ** the array as
a5e0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e the only argumen
a5f0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 t. If it returns
a600: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
a610: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
a620: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 should be retri
a630: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e ed. If it return
a640: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 s zero, the cust
a650: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 om VFS should ab
a660: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 andon the.** cur
a670: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a rent operation..
a680: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a690: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
a6a0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c ENAME]].** ^Appl
a6b0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f ication can invo
a6c0: 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e ke this file-con
a6d0: 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53 51 4c trol to have SQL
a6e0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a ite generate a.*
a6f0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
a700: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 name using the s
a710: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 ame algorithm th
a720: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 at is followed t
a730: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 o generate.** te
a740: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 mporary filename
a750: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 s for TEMP table
a760: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 s and other inte
a770: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a rnal uses. The.
a780: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
a790: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 ld be a char** w
a7a0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c hich will be fil
a7b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c led with the fil
a7c0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e ename.** written
a7d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
a7e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
a7f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
a800: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c The caller shoul
a810: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c d.** invoke [sql
a820: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 ite3_free()] on
a830: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 the result to av
a840: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 oid a memory lea
a850: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a k..**.** </ul>.*
a860: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
a870: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
a880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
a890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a8a0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
a8b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a E 2.
a8c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
a8d0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
a8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 3.#
a8f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 define SQLITE_LA
a900: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 ST_ERRNO
a910: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 4.#d
a920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
a930: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 TL_SIZE_HINT
a940: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
a950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
a960: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 L_CHUNK_SIZE
a970: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
a980: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
a990: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 _FILE_POINTER
a9a0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
a9b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
a9c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 SYNC_OMITTED
a9d0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 8.#defin
a9e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
a9f0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 IN32_AV_RETRY
aa00: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
aa10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 SQLITE_FCNTL_PE
aa20: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 RSIST_WAL
aa30: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 10.#define
aa40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
aa50: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 RWRITE
aa60: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 11.#define S
aa70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
aa80: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 AME
aa90: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 12.#define SQ
aaa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
aab0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 SAFE_OVERWRITE
aac0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 13.#define SQL
aad0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
aae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
aaf0: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 14.#define SQLI
ab00: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
ab10: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 DLER
ab20: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 15.#define SQLIT
ab30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
ab40: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 NAME 1
ab50: 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 6../*.** CAPI3RE
ab60: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a F: Mutex Handle.
ab70: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 **.** The mutex
ab80: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 module within SQ
ab90: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 Lite defines [sq
aba0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 lite3_mutex] to
abb0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 be an.** abstrac
abc0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 t type for a mut
abd0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 ex object. The
abe0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 SQLite core neve
abf0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 r looks.** at th
ac00: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
ac10: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 sentation of an
ac20: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e [sqlite3_mutex].
ac30: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 It only.** dea
ac40: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 ls with pointers
ac50: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
ac60: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a _mutex] object..
ac70: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 **.** Mutexes ar
ac80: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 e created using
ac90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
aca0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 lloc()]..*/.type
acb0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
acc0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 e3_mutex sqlite3
acd0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _mutex;../*.** C
ace0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
acf0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a rface Object.**.
ad00: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
ad10: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
ad20: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
ad30: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
ad40: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
ad50: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
ad60: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
ad70: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
ad80: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
ad90: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
ada0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
adb0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
adc0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a system". See.**
add0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 the [VFS | VFS
ade0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
adf0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 or further infor
ae00: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
ae10: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 e value of the i
ae20: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 Version field is
ae30: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 initially 1 but
ae40: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 may be larger i
ae50: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 n.** future vers
ae60: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ions of SQLite.
ae70: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c Additional fiel
ae80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
ae90: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 ed to this.** ob
aea0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 ject when the iV
aeb0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 ersion value is
aec0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 increased. Note
aed0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 that the struct
aee0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ure.** of the sq
aef0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
af00: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
af10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 transaction betw
af20: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 een.** SQLite ve
af30: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 rsion 3.5.9 and
af40: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 3.6.0 and yet th
af50: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
af60: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 was not.** modi
af70: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fied..**.** The
af80: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 szOsFile field i
af90: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
afa0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 e subclassed [sq
afb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 lite3_file].** s
afc0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 tructure used by
afd0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 this VFS. mxPa
afe0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 thname is the ma
aff0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a ximum length of.
b000: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e ** a pathname in
b010: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a this VFS..**.**
b020: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 Registered sqli
b030: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 te3_vfs objects
b040: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 are kept on a li
b050: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 nked list formed
b060: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 by.** the pNext
b070: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b pointer. The [
b080: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
b090: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b ster()].** and [
b0a0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
b0b0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 gister()] interf
b0c0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 aces manage this
b0d0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 list.** in a th
b0e0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 read-safe way.
b0f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
b100: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 _find()] interfa
b110: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 ce.** searches t
b120: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 he list. Neithe
b130: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
b140: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 n code nor the V
b150: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 FS.** implementa
b160: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 tion should use
b170: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
b180: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 r..**.** The pNe
b190: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 xt field is the
b1a0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 only field in th
b1b0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
b1c0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
b1d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 SQLite will ever
b1e0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 modify. SQLite
b1f0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 will only acces
b200: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 s.** or modify t
b210: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 his field while
b220: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 holding a partic
b230: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 ular static mute
b240: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 x..** The applic
b250: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
b260: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 er modify anythi
b270: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 ng within the sq
b280: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a lite3_vfs.** obj
b290: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a ect once the obj
b2a0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 ect has been reg
b2b0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 istered..**.** T
b2c0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 he zName field h
b2d0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 olds the name of
b2e0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e the VFS module.
b2f0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a The name must.
b300: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 ** be unique acr
b310: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 oss all VFS modu
b320: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c les..**.** [[sql
b330: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d ite3_vfs.xOpen]]
b340: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 .** ^SQLite guar
b350: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
b360: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
b370: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 ter to xOpen.**
b380: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c is either a NULL
b390: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 pointer or stri
b3a0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ng obtained.** f
b3b0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d rom xFullPathnam
b3c0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 e() with an opti
b3d0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 onal suffix adde
b3e0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 d..** ^If a suff
b3f0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 ix is added to t
b400: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
b410: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a ameter, it will.
b420: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 ** consist of a
b430: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 single "-" chara
b440: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 cter followed by
b450: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a no more than.**
b460: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 11 alphanumeric
b470: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 and/or "-" char
b480: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 acters..** ^SQLi
b490: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 te further guara
b4a0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 ntees that.** th
b4b0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
b4c0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 valid and uncha
b4d0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 nged until xClos
b4e0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 e() is.** called
b4f0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 . Because of the
b500: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
b510: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ce,.** the [sqli
b520: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 te3_file] can sa
b530: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 fely store a poi
b540: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 nter to the.** f
b550: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 ilename if it ne
b560: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 eds to remember
b570: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 the filename for
b580: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a some reason..**
b590: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d If the zFilenam
b5a0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
b5b0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 Open is a NULL p
b5c0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 ointer then xOpe
b5d0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 n.** must invent
b5e0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 its own tempora
b5f0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 ry name for the
b600: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 file. ^Whenever
b610: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 the .** xFilena
b620: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
b630: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 NULL it will als
b640: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 o be the case th
b650: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 at the.** flags
b660: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 parameter will i
b670: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
b680: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
b690: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c E]..**.** The fl
b6a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
b6b0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 xOpen() includes
b6c0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e all bits set in
b6d0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 .** the flags ar
b6e0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
b6f0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 e3_open_v2()].
b700: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f Or if [sqlite3_o
b710: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 pen()].** or [sq
b720: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
b730: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c is used, then fl
b740: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 ags includes at
b750: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 least.** [SQLITE
b760: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
b770: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
b780: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 CREATE]. .** If
b790: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
b7a0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
b7b0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
b7c0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
b7d0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
b7e0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
b7f0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
b800: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
b810: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 t..**.** ^(SQLit
b820: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 e will also add
b830: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
b840: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
b850: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c e xOpen().** cal
b860: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 l, depending on
b870: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 the object being
b880: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c opened:.**.** <
b890: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 ul>.** <li> [SQ
b8a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
b8b0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
b8c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
b8d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
b8e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
b8f0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b P_DB].** <li> [
b900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
b910: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
b920: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
b930: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a TRANSIENT_DB].**
b940: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
b950: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a PEN_SUBJOURNAL].
b960: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
b970: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
b980: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
b990: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d SQLITE_OPEN_WAL]
b9a0: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
b9b0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 * The file I/O i
b9c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
b9d0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 n use the object
b9e0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a type flags to.*
b9f0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 * change the way
ba00: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
ba10: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
ba20: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
ba30: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
ba40: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
ba50: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
ba60: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 rollback might
ba70: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e make.** the open
ba80: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 of a journal fi
ba90: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 le a no-op. Wri
baa0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 tes to this jour
bab0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 nal would.** als
bac0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 o be no-ops, and
bad0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 any attempt to
bae0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c read the journal
baf0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a would return.**
bb00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 SQLITE_IOERR.
bb10: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 Or the implement
bb20: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f ation might reco
bb30: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 gnize that a dat
bb40: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 abase.** file wi
bb50: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 ll be doing page
bb60: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 -aligned sector
bb70: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
bb80: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 in a random.**
bb90: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 order and set up
bba0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 its I/O subsyst
bbb0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a em accordingly..
bbc0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 **.** SQLite mig
bbd0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ht also add one
bbe0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
bbf0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
bc00: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a pen method:.**.*
bc10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
bc20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
bc30: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
bc40: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
bc50: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
bc60: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ul>.**.** The [S
bc70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
bc80: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d EONCLOSE] flag m
bc90: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
bca0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 ould be.** delet
bcb0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c ed when it is cl
bcc0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c osed. ^The [SQL
bcd0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
bce0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
bcf0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
bd00: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 databases and th
bd10: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 eir journals, tr
bd20: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 ansient.** datab
bd30: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 ases, and subjou
bd40: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rnals..**.** ^Th
bd50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
bd60: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 XCLUSIVE] flag i
bd70: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e s always used in
bd80: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 conjunction.**
bd90: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
bda0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c _OPEN_CREATE] fl
bdb0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f ag, which are bo
bdc0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 th directly.** a
bdd0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 nalogous to the
bde0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 O_EXCL and O_CRE
bdf0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 AT flags of the
be00: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 POSIX open().**
be10: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 API. The SQLITE
be20: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
be30: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 flag, when paire
be40: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
be50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
be60: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e E, is used to in
be70: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 dicate that file
be80: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a should always.*
be90: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e * be created, an
bea0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 d that it is an
beb0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 error if it alre
bec0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 ady exists..** I
bed0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 t is <i>not</i>
bee0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
bef0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
bf00: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 be opened .** f
bf10: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 or exclusive acc
bf20: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c ess..**.** ^At l
bf30: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 east szOsFile by
bf40: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 tes of memory ar
bf50: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 e allocated by S
bf60: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 QLite.** to hold
bf70: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 the [sqlite3_f
bf80: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 ile] structure p
bf90: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 assed as the thi
bfa0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 rd.** argument t
bfb0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f o xOpen. The xO
bfc0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 pen method does
bfd0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 not have to.** a
bfe0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 llocate the stru
bff0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 cture; it should
c000: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e just fill it in
c010: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 . Note that.**
c020: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
c030: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 must set the sq
c040: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
c050: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a ods to either.**
c060: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 a valid [sqlite
c070: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
c080: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e ject or to NULL.
c090: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a xOpen must do.
c0a0: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 ** this even if
c0b0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 the open fails.
c0c0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 SQLite expects
c0d0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 that the sqlite3
c0e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a _file.pMethods.*
c0f0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 * element will b
c100: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f e valid after xO
c110: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 pen returns rega
c120: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 rdless of the su
c130: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c ccess.** or fail
c140: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e ure of the xOpen
c150: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 call..**.** [[s
c160: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 qlite3_vfs.xAcce
c170: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 ss]].** ^The fla
c180: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
c190: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 Access() may be
c1a0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 [SQLITE_ACCESS_E
c1b0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 XISTS].** to tes
c1c0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 t for the existe
c1d0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f nce of a file, o
c1e0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
c1f0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a _READWRITE] to.*
c200: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 * test whether a
c210: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
c220: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
c230: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
c240: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 S_READ].** to te
c250: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
c260: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 e is at least re
c270: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 adable. The fi
c280: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
c290: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
c2a0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 ^SQLite will alw
c2b0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
c2c0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
c2d0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
c2e0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
c2f0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
c300: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 The exact size
c310: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
c320: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
c330: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
c340: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
c350: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 methods. If the
c360: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
c370: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
c380: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
c390: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
c3a0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
c3b0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
c3c0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
c3d0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
c3e0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
c3f0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
c400: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
c410: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
c420: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
c430: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
c440: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
c450: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
c460: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
c470: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 xCurrentTime(),
c480: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
c490: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 Int64().** inter
c4a0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 faces are not st
c4b0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
c4c0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
c4d0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
c4e0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
c4f0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
c500: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
c510: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
c520: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
c530: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
c540: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
c550: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
c560: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
c570: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
c580: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
c590: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
c5a0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
c5b0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
c5c0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
c5d0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
c5e0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
c5f0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
c600: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
c610: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
c620: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
c630: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
c640: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
c650: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
c660: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
c670: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
c680: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 nd time as.** a
c690: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
c6a0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 alue..** ^The xC
c6b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
c6c0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
c6d0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c , as an integer,
c6e0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 the Julian.** D
c6f0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 ay Number multip
c700: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 lied by 86400000
c710: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 (the number of
c720: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 milliseconds in
c730: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 .** a 24-hour da
c740: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 y). .** ^SQLite
c750: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 will use the xC
c760: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
c770: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 ) method to get
c780: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 the current.** d
c790: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 ate and time if
c7a0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 that method is a
c7b0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 vailable (if iVe
c7c0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a rsion is 2 or .*
c7d0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 * greater and th
c7e0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 e function point
c7f0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 er is not NULL)
c800: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 and will fall ba
c810: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e ck.** to xCurren
c820: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 tTime() if xCurr
c830: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 entTimeInt64() i
c840: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
c850: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 *.** ^The xSetSy
c860: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 stemCall(), xGet
c870: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e SystemCall(), an
c880: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c d xNestSystemCal
c890: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a l() interfaces.*
c8a0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 * are not used b
c8b0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 y the SQLite cor
c8c0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e e. These option
c8d0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
c8e0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 e provided.** by
c8f0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 some VFSes to f
c900: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e acilitate testin
c910: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 g of the VFS cod
c920: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 e. By overriding
c930: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c .** system call
c940: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 s with functions
c950: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 under its contr
c960: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 ol, a test progr
c970: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 am can.** simula
c980: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 te faults and er
c990: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 ror conditions t
c9a0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 hat would otherw
c9b0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 ise be difficult
c9c0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c .** or impossibl
c9d0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 e to induce. Th
c9e0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 e set of system
c9f0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 calls that can b
ca00: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 e overridden.**
ca10: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 varies from one
ca20: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 VFS to another,
ca30: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 and from one ver
ca40: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 sion of the same
ca50: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e VFS to the.** n
ca60: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
ca70: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 ns that use thes
ca80: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 e interfaces mus
ca90: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f t be prepared fo
caa0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 r any.** or all
cab0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 of these interfa
cac0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f ces to be NULL o
cad0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 r for their beha
cae0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a vior to change.*
caf0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 * from one relea
cb00: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 se to the next.
cb10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 Applications mu
cb20: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 st not attempt t
cb30: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 o access.** any
cb40: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 of these methods
cb50: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e if the iVersion
cb60: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c of the VFS is l
cb70: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 ess than 3..*/.t
cb80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
cb90: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
cba0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 3_vfs;.typedef v
cbb0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 oid (*sqlite3_sy
cbc0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 scall_ptr)(void)
cbd0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
cbe0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 _vfs {. int iVe
cbf0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 rsion;
cc00: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 /* Structure v
cc10: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 ersion number (c
cc20: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 urrently 3) */.
cc30: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
cc40: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
cc50: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
cc60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
cc70: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
cc80: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
cc90: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
cca0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
ccb0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
ccc0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
ccd0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
cce0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
ccf0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
cd00: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
cd10: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
cd20: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
cd30: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
cd40: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
cd50: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
cd60: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
cd70: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
cd80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
cd90: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
cda0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
cdb0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
cdc0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
cdd0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
cde0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
cdf0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ce00: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
ce10: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
ce20: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
ce30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ce40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
ce50: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
ce60: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
ce70: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f thname)(sqlite3_
ce80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
ce90: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 *zName, int nOu
cea0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a t, char *zOut);.
ceb0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 void *(*xDlOpe
cec0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
ced0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
cee0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 lename);. void
cef0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 (*xDlError)(sqli
cf00: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
cf10: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d yte, char *zErrM
cf20: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a sg);. void (*(*
cf30: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
cf40: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
cf50: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
cf60: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 )(void);. void
cf70: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 (*xDlClose)(sqli
cf80: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 te3_vfs*, void*)
cf90: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f ;. int (*xRando
cfa0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 mness)(sqlite3_v
cfb0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
cfc0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 char *zOut);. i
cfd0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c nt (*xSleep)(sql
cfe0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
cff0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 icroseconds);.
d000: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
d010: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
d020: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e , double*);. in
d030: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f t (*xGetLastErro
d040: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
d050: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 int, char *);.
d060: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
d070: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
d080: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
d090: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
d0a0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 ject. ** defini
d0b0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 tion. Those tha
d0c0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 t follow are add
d0d0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 ed in version 2
d0e0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 or later. */.
d0f0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
d100: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 meInt64)(sqlite3
d110: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 _vfs*, sqlite3_i
d120: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a nt64*);. /*. *
d130: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
d140: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
d150: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 ons 1 and 2 of t
d160: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
d170: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 ject.. ** Those
d180: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 below are for v
d190: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 ersion 3 and gre
d1a0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 ater.. */. int
d1b0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c (*xSetSystemCal
d1c0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
d1d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
d1e0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 me, sqlite3_sysc
d1f0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 all_ptr);. sqli
d200: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 te3_syscall_ptr
d210: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xGetSystemCall
d220: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d230: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
d240: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 e);. const char
d250: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 *(*xNextSystemC
d260: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
d270: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
d280: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a Name);. /*. **
d290: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
d2a0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
d2b0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f ns 1 through 3 o
d2c0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
d2d0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 object.. ** Ne
d2e0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
d2f0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
d300: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
d310: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
d320: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
d330: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
d340: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a is happens. . *
d350: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
d360: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
d370: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
d380: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
d390: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
d3a0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 ants can be used
d3b0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 as the third pa
d3c0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
d3d0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
d3e0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
d3f0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 vfs] object. Th
d400: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 ey determine.**
d410: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 what kind of per
d420: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 missions the xAc
d430: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c cess method is l
d440: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 ooking for..** W
d450: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
d460: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
d470: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
d480: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 simply checks wh
d490: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 ether the file e
d4a0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 xists..** With S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 DWRITE, the xAcc
d4d0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
d4e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
d4f0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 named directory
d500: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c is both readabl
d510: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a e and writable.*
d520: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 * (in other word
d530: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 s, if files can
d540: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 be added, remove
d550: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 d, and renamed w
d560: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 ithin.** the dir
d570: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 ectory)..** The
d580: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
d590: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 ADWRITE constant
d5a0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 is currently us
d5b0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a ed only by the.*
d5c0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 * [temp_store_di
d5d0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c rectory pragma],
d5e0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 though this cou
d5f0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ld change in a f
d600: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
d610: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 of SQLite..** W
d620: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
d630: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 S_READ, the xAcc
d640: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
d650: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
d660: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
d670: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 e. The SQLITE_A
d680: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 CCESS_READ const
d690: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e ant is.** curren
d6a0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 tly unused, thou
d6b0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 gh it might be u
d6c0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 sed in a future
d6d0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
d6e0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
d6f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
d700: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
d710: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
d720: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f _READWRITE 1 /
d730: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 * Used by PRAGMA
d740: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 temp_store_dire
d750: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ctory */.#define
d760: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
d770: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 EAD 2 /*
d780: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a Unused */../*.**
d790: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
d7a0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 for the xShmLoc
d7b0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a k VFS method.**.
d7c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
d7d0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
d7e0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f e the various lo
d7f0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 cking operations
d800: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 .** allowed by t
d810: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
d820: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 od of [sqlite3_i
d830: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 o_methods]. The
d840: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 .** following ar
d850: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c e the only legal
d860: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 combinations of
d870: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a flags to the.**
d880: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
d890: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
d8a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
d8b0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 _LOCK | SQLITE_S
d8c0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 HM_SHARED.** <li
d8d0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
d8e0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
d8f0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 EXCLUSIVE.** <li
d900: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e > SQLITE_SHM_UN
d910: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
d920: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
d930: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
d940: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
d950: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f _EXCLUSIVE.** </
d960: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 ul>.**.** When u
d970: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 nlocking, the sa
d980: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 me SHARED or EXC
d990: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 LUSIVE flag must
d9a0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a be supplied as.
d9b0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 ** was given no
d9c0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
d9d0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 g lock. .**.**
d9e0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 The xShmLock met
d9f0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 hod can transiti
da00: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 on between unloc
da10: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f ked and SHARED o
da20: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c r.** between unl
da30: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 ocked and EXCLUS
da40: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 IVE. It cannot
da50: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
da60: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 en SHARED.** and
da70: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 EXCLUSIVE..*/.#
da80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
da90: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 M_UNLOCK 1
daa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dab0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 SHM_LOCK
dac0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
dad0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 E_SHM_SHARED
dae0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
daf0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
db00: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 E 8../*.** CA
db10: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 PI3REF: Maximum
db20: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a xShmLock index.*
db30: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
db40: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c k method on [sql
db50: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
db60: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a may use values.
db70: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ** between 0 and
db80: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e this upper boun
db90: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 d as its "offset
dba0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 " argument..** T
dbb0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 he SQLite core w
dbc0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 ill never attemp
dbd0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 t to acquire or
dbe0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 release a.** loc
dbf0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 k outside of thi
dc00: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 s range.*/.#defi
dc10: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c ne SQLITE_SHM_NL
dc20: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f OCK 8.../
dc30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
dc40: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
dc50: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
dc60: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
dc70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
dc80: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
dc90: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
dca0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
dcb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
dcc0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
dcd0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
dce0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
dcf0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
dd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
dd10: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
dd20: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
dd30: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
dd40: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
dd50: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
dd60: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
dd70: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
dd80: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
dd90: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
dda0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
ddb0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
ddc0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
ddd0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
dde0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
ddf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
de00: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
de10: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
de20: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
de30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
de40: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
de50: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
de60: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
de70: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
de80: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
de90: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
dea0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
deb0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
dec0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
ded0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
dee0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
def0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
df00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
df10: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
df20: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
df30: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
df40: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
df50: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
df60: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
df70: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
df80: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
df90: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
dfa0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
dfb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
dfc0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
dfd0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
dfe0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
dff0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
e000: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
e010: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
e020: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
e030: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
e040: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
e050: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
e060: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
e070: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
e080: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
e090: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
e0a0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
e0b0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
e0c0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
e0d0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
e0e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
e0f0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
e100: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
e110: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
e120: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
e130: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e140: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
e150: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
e160: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
e170: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
e180: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
e190: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
e1a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
e1b0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
e1c0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
e1d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e1e0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
e1f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
e200: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
e210: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
e220: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
e230: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
e240: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
e250: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e260: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
e270: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
e280: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
e290: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
e2a0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
e2b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
e2c0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
e2d0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
e2e0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
e2f0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
e300: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
e310: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
e320: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
e330: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
e340: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
e350: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
e360: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
e370: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
e380: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
e390: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
e3a0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
e3b0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
e3c0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
e3d0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
e3e0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
e3f0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
e400: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
e410: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
e420: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
e430: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
e440: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e450: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
e460: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
e470: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
e480: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
e490: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
e4a0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
e4b0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
e4c0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
e4d0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
e4e0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
e4f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
e500: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
e510: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
e520: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
e530: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
e540: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
e550: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e560: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
e570: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
e580: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
e590: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e5a0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
e5b0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
e5c0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
e5d0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
e5e0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
e5f0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
e600: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
e610: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
e620: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
e630: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
e640: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
e650: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
e660: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
e670: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
e680: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
e690: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
e6a0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
e6b0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
e6c0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
e6d0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
e6e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
e6f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
e700: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
e710: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
e720: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
e730: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
e740: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
e750: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
e760: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
e770: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
e780: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
e790: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
e7a0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
e7b0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
e7c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
e7d0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
e7e0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
e7f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
e800: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
e810: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
e820: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
e830: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
e840: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
e850: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
e860: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
e870: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
e880: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
e890: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
e8a0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
e8b0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
e8c0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
e8d0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
e8e0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
e8f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
e900: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
e910: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
e920: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
e930: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
e940: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
e950: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
e960: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
e970: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
e980: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
e990: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
e9a0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
e9b0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
e9c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
e9d0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
e9e0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
e9f0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
ea00: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
ea10: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
ea20: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
ea30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ea40: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
ea50: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
ea60: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
ea70: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
ea80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
ea90: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
eaa0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
eab0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
eac0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
ead0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
eae0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
eaf0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
eb00: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
eb10: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
eb20: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
eb30: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
eb40: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
eb50: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
eb60: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
eb70: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
eb80: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
eb90: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
eba0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
ebb0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
ebc0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
ebd0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
ebe0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
ebf0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
ec00: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
ec10: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
ec20: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
ec30: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
ec40: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
ec50: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
ec60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
ec70: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
ec80: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
ec90: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
eca0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
ecb0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
ecc0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
ecd0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
ece0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
ecf0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ary.**.** The sq
ed00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
ed10: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
ed20: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
ed30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
ed40: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
ed50: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
ed60: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
ed70: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
ed80: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
ed90: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
eda0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
edb0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
edc0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
edd0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
ede0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
edf0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
ee00: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
ee10: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
ee20: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
ee30: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
ee40: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
ee50: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
ee60: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
ee70: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
ee80: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
ee90: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
eea0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
eeb0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
eec0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
eed0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
eee0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
eef0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
ef00: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
ef10: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
ef20: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
ef30: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
ef40: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
ef50: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
ef60: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
ef70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
ef80: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
ef90: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
efa0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
efb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
efc0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
efd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
efe0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
eff0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
f000: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
f010: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
f020: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
f030: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
f040: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
f050: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
f060: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
f070: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
f080: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
f090: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
f0a0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
f0b0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
f0c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
f0d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
f0e0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
f0f0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f ** [configuratio
f100: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
f110: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
f120: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
f130: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
f140: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
f150: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
f160: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
f170: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 g on the [config
f180: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
f190: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
f1a0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
f1b0: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
f1c0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
f1d0: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
f1e0: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
f1f0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
f200: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
f210: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
f220: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
f230: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
f240: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
f250: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
f260: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
f270: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
f280: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
f290: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
f2a0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
f2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f2c0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ions.**.** The s
f2d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
f2e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
f2f0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e used to make con
f300: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
f310: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 anges to a [data
f320: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
f330: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
f340: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a is similar to.*
f350: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
f360: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 g()] except that
f370: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 the changes app
f380: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a ly to a single.*
f390: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
f3a0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 ection] (specifi
f3b0: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
f3c0: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a argument)..**.**
f3d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
f3e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
f3f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e db_config(D,V,..
f400: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 .) is the.** [S
f410: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
f420: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 OOKASIDE | confi
f430: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d guration verb] -
f440: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
f450: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 .** that indica
f460: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 tes what aspect
f470: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
f480: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
f490: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
f4a0: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 ..** Subsequent
f4b0: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 arguments vary d
f4c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
f4d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
f4e0: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 rb..**.** ^Calls
f4f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
f500: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 onfig() return S
f510: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 QLITE_OK if and
f520: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 only if.** the c
f530: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 all is considere
f540: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f d successful..*/
f550: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f .int sqlite3_db_
f560: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
f570: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
f580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f590: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
f5a0: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
f5b0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
f5c0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
f5d0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
f5e0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
f5f0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
f600: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
f610: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
f620: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
f630: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
f640: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
f650: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
f660: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
f670: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
f680: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
f690: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
f6a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
f6b0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
f6c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
f6d0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
f6e0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
f6f0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
f700: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
f710: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
f720: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
f730: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
f740: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
f750: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
f760: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
f770: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
f780: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
f790: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
f7a0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
f7b0: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
f7c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f7d0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
f7e0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
f7f0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
f800: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
f810: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
f820: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
f830: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
f840: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
f850: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
f860: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
f870: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
f880: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
f890: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
f8a0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
f8b0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
f8c0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
f8d0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
f8e0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
f8f0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
f900: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
f910: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
f920: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
f930: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
f940: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
f950: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
f960: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
f970: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
f980: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
f990: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
f9a0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
f9b0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
f9c0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
f9d0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
f9e0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
f9f0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
fa00: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
fa10: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
fa20: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
fa30: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
fa40: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
fa50: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
fa60: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
fa70: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
fa80: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
fa90: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
faa0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
fab0: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
fac0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
fad0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
fae0: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
faf0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
fb00: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
fb10: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
fb20: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
fb30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
fb40: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
fb50: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
fb60: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
fb70: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
fb80: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
fb90: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
fba0: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
fbb0: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
fbc0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
fbd0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
fbe0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
fbf0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
fc00: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
fc10: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
fc20: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
fc30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
fc40: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
fc50: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
fc60: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
fc70: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
fc80: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
fc90: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
fca0: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
fcb0: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
fcc0: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
fcd0: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
fce0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
fcf0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
fd00: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
fd10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
fd20: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
fd30: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
fd40: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
fd50: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
fd60: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
fd70: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
fd80: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
fd90: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
fda0: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
fdb0: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
fdc0: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
fdd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
fde0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
fdf0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
fe00: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
fe10: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
fe20: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
fe30: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
fe40: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
fe50: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
fe60: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
fe70: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
fe80: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
fe90: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
fea0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
feb0: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
fec0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
fed0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
fee0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
fef0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
ff00: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
ff10: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
ff20: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
ff30: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
ff40: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
ff50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
ff60: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
ff70: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
ff80: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
ff90: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
ffa0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
ffb0: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
ffc0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
ffd0: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
ffe0: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
fff0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
10000 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
10010 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
10020 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
10030 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
10040 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
10050 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
10060 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
10070 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
10080 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
10090 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
100a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
100b0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
100c0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
100d0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
100e0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
100f0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
10100 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
10110 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
10120 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
10130 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
10140 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
10150 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
10160 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
10170 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
10180 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
10190 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
101a0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
101b0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
101c0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
101d0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
101e0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
101f0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
10200 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
10210 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
10220 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
10230 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10240 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
10250 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
10260 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10270 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
10280 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
10290 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
102a0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
102b0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
102c0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
102d0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
102e0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
102f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
10300 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
10310 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
10320 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
10330 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
10340 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
10350 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
10360 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
10370 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
10380 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
10390 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
103a0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
103b0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
103c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
103d0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
103e0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
103f0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
10400 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
10410 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
10420 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
10430 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
10440 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
10450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
10460 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
10470 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
10480 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
10490 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
104a0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
104b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
104c0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
104d0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
104e0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
104f0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
10500 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
10510 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
10520 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
10530 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
10540 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
10550 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
10560 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10570 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
10580 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
10590 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
105a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
105b0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
105c0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
105d0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
105e0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
105f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
10600 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
10610 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
10620 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
10630 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
10640 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
10650 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
10660 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
10670 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
10680 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
10690 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
106a0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
106b0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
106c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
106d0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
106e0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
106f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10700 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
10710 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
10720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
10730 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
10740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
10750 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
10760 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
10770 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
10780 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
10790 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
107a0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
107b0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
107c0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
107d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
107e0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
107f0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
10800 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
10810 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
10820 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
10830 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
10840 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
10850 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10860 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
10870 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
10880 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
10890 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
108a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
108b0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
108c0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
108d0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
108e0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
108f0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
10900 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
10910 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
10920 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
10930 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
10940 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
10950 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
10960 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
10970 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
10980 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
10990 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
109a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
109b0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
109c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
109d0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
109e0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
109f0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
10a00 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
10a10 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
10a20 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
10a30 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
10a40 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
10a50 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
10a60 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
10a70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10a80 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
10a90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
10aa0 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
10ab0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
10ac0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
10ad0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
10ae0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
10af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
10b00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
10b10 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
10b20 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
10b30 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
10b40 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
10b50 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
10b60 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
10b70 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
10b80 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
10b90 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
10ba0 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
10bb0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
10bc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
10bd0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
10be0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
10bf0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
10c00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
10c10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
10c20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
10c30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
10c40 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
10c50 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
10c60 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
10c70 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
10c80 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
10c90 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
10ca0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
10cb0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
10cc0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
10cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
10ce0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
10cf0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
10d00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
10d10 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
10d20 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
10d30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
10d40 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
10d50 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
10d60 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
10d70 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
10d80 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
10d90 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
10da0 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
10db0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
10dc0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
10dd0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
10de0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
10df0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
10e00 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
10e10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10e20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
10e30 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
10e40 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
10e50 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
10e60 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
10e70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
10e80 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
10e90 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
10ea0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
10eb0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
10ec0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
10ed0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
10ee0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
10ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
10f00 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
10f10 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
10f20 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
10f30 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
10f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
10f50 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
10f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
10f70 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
10f80 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
10f90 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
10fa0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
10fb0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
10fc0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
10fd0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
10fe0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
10ff0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
11000 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
11010 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
11020 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
11030 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11040 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
11050 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
11060 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
11070 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
11080 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
11090 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
110a0 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
110b0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
110c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
110d0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
110e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
110f0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
11100 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
11110 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
11120 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
11130 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
11140 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
11150 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
11160 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
11170 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
11180 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
11190 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
111a0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
111b0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
111c0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
111d0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
111e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
111f0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
11200 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
11210 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
11220 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
11230 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
11240 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
11250 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
11260 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
11270 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
11280 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
11290 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
112a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
112b0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
112c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
112d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
112e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
112f0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
11300 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
11310 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
11320 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
11330 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
11340 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11350 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
11360 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
11370 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
11380 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
11390 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
113a0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
113b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
113c0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
113d0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
113e0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
113f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
11400 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
11410 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
11420 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
11430 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
11440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
11450 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
11460 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
11470 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
11480 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
11490 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
114a0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
114b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
114c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
114d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
114e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
114f0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
11500 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
11510 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
11520 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
11530 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
11540 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
11550 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
11560 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11580 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11590 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 e disabled, the
115a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 .** following SQ
115b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
115c0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
115d0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
115e0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
115f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
11600 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
11610 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
11620 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
11630 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
11640 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
11650 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
11660 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
11670 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
11680 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
11690 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
116a0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
116b0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
116c0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
116d0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
116e0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
116f0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
11700 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
11710 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
11720 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
11730 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
11740 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11750 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
11760 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
11770 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
11780 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
11790 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
117a0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
117b0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
117c0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
117d0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
117e0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
117f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
11800 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
11810 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
11820 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
11830 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
11840 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
11850 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
11860 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
11870 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
11880 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
11890 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
118a0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
118b0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
118c0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
118d0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
118e0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
118f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
11900 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11910 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
11920 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
11930 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
11940 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
11950 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
11960 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
11970 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 more than two s
11980 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 cratch buffers p
11990 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
119a0 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
119b0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 t to twice the e
119c0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
119d0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
119e0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 s..** ^SQLite wi
119f0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ll never require
11a00 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
11a10 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
11a20 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
11a30 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
11a40 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
11a50 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
11a60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
11a70 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
11a80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
11a90 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
11aa0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
11ab0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
11ac0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
11ad0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
11ae0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
11af0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a eeded.</dd>.**.*
11b00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
11b10 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
11b20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11b30 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
11b40 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
11b50 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
11b60 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
11b70 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
11b80 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
11b90 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
11ba0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
11bb0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
11bc0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
11bd0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
11be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
11bf0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
11c00 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
11c10 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
11c20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
11c30 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
11c40 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
11c50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
11c60 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
11c70 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
11c80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
11c90 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
11ca0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
11cb0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
11cc0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
11cd0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
11ce0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
11cf0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
11d00 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
11d10 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
11d20 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
11d30 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
11d40 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
11d50 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
11d60 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
11d70 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
11d80 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
11d90 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
11da0 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
11db0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
11dc0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
11dd0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
11de0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
11df0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
11e00 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
11e10 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
11e20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
11e30 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
11e40 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
11e50 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
11e60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
11e70 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
11e80 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
11e90 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
11ea0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
11eb0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
11ec0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
11ed0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
11ee0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
11ef0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
11f00 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
11f10 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
11f20 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
11f30 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
11f40 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
11f50 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
11f60 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
11f70 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
11f80 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
11f90 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
11fa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
11fb0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
11fc0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
11fd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
11fe0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
11ff0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
12000 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
12010 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
12020 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
12030 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
12040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12050 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
12060 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12070 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
12080 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
12090 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
120a0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
120b0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
120c0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
120d0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
120e0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
120f0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
12100 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
12110 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
12120 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
12130 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
12140 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
12150 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
12160 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
12170 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
12180 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
12190 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
121a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
121b0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
121c0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
121d0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
121e0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
121f0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
12200 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
12210 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
12220 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
12230 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
12240 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
12250 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
12260 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
12270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
12280 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
12290 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
122a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
122b0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
122c0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
122d0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
122e0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
122f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
12300 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
12310 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
12320 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
12330 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
12340 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
12350 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
12360 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
12370 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
12380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12390 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
123a0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
123b0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
123c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
123d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
123e0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
123f0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
12400 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
12410 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
12420 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
12430 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
12440 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
12450 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
12460 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
12470 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
12480 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
12490 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
124a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
124b0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
124c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
124d0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
124e0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
124f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12500 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12520 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12530 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12540 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12550 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
12560 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
12570 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
12580 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
12590 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
125a0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a used in place.**
125b0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
125c0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
125d0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
125e0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
125f0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 f the.** content
12600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
12620 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
12630 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
12640 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12650 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
12660 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
12670 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
12680 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12690 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
126a0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
126b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
126c0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
126d0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
126e0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
126f0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
12700 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
12710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
12720 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
12730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
12740 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
12750 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
12760 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12770 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
12780 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12790 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
127a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
127b0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
127c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
127d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
127e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
127f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12800 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12810 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12820 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12830 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
12840 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
12850 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12860 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12870 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12880 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
12890 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
128a0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
128b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
128c0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
128d0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
128e0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
128f0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
12900 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
12910 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
12920 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
12930 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
12940 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
12950 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12960 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12970 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12980 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
12990 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
129a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
129b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
129c0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
129d0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
129e0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
129f0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
12a00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
12a10 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
12a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
12a30 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
12a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
12a50 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
12a60 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
12a70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
12a90 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
12aa0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
12ab0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
12ac0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
12ad0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
12ae0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
12af0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
12b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
12b10 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
12b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
12b30 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
12b40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12b50 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
12b60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
12b70 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
12b80 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
12b90 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
12ba0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
12bb0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
12bc0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
12bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12be0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
12bf0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
12c00 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
12c10 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
12c20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
12c30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
12c40 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
12c50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
12c60 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
12c70 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
12c80 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
12c90 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
12ca0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
12cb0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
12cc0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12cd0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
12ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
12cf0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
12d00 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
12d10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
12d20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
12d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
12d40 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
12d50 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
12d60 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
12d70 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
12d80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
12d90 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
12da0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
12db0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d on.)^ ^SQLite m
12dc0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
12dd0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 he.** object and
12de0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 uses it for pag
12df0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 e cache memory a
12e00 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e llocations.</dd>
12e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12e20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
12e30 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
12e40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
12e50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
12e60 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
12e70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
12e80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
12e90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
12ea0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
12eb0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
12ec0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
12ed0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
12ee0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
12ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
12f00 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
12f10 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
12f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
12f30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12f40 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
12f50 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
12f60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
12f70 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
12f80 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 guments: a point
12f90 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 er to a.** funct
12fa0 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 ion with a call
12fb0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 signature of voi
12fc0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 d(*)(void*,int,c
12fd0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a onst char*), .**
12fe0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 and a pointer t
12ff0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 o void. ^If the
13000 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
13010 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 is not NULL, it
13020 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 is.** invoked b
13030 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 y [sqlite3_log()
13040 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 ] to process eac
13050 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e h logging event.
13060 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e ^If the.** fun
13070 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
13080 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 NULL, the [sqli
13090 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 te3_log()] inter
130a0 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e face becomes a n
130b0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f o-op..** ^The vo
130c0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 id pointer that
130d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 is the second ar
130e0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 gument to SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a _CONFIG_LOG is.*
13100 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 * passed through
13110 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 as the first pa
13120 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
13130 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
13140 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
13150 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 ction whenever t
13160 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 hat function is
13170 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 invoked. ^The s
13180 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
13190 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 to.** the logger
131a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 function is a c
131b0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 opy of the first
131c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
131d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
131e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 ** [sqlite3_log(
131f0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 )] call and is i
13200 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 ntended to be a
13210 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
13220 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 an.** [extended
13230 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 result code].
13240 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
13250 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 eter passed to t
13260 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 he logger is.**
13270 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 log message afte
13280 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 r formatting via
13290 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
132a0 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 tf()]..** The SQ
132b0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 Lite logging int
132c0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
132d0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 entrant; the log
132e0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ger function.**
132f0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 supplied by the
13300 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
13310 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 not invoke any
13320 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
13330 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d ..** In a multi-
13340 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
13350 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 tion, the applic
13360 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
13370 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
13380 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
13390 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a afe. </dd>.**.**
133a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
133b0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _URI]] <dt>SQLIT
133c0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 E_CONFIG_URI.**
133d0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e <dd> This option
133e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
133f0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
13400 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 int. If non-zer
13410 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 o, then.** URI h
13420 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
13430 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 lly enabled. If
13440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
13450 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 zero, then URI
13460 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 handling.** is g
13470 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
13480 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e . If URI handlin
13490 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
134a0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
134b0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 ames.** passed t
134c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
134d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
134e0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 n_v2()], [sqlite
134f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
13500 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
13510 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
13520 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
13530 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
13540 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
13550 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
13560 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
13570 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
13580 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
13590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
135a0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 ion is opened. I
135b0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
135c0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
135d0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
135e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
135f0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
13600 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
13610 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
13620 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
13630 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
13640 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 d. By default, U
13650 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
13660 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
13670 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
13680 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
13690 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
136a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
136b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
136c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
136d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
136e0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
136f0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e NDEX_SCAN]] <dt>
13700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
13710 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
13720 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f N.** <dd> This o
13730 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
13740 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 ngle integer arg
13750 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 ument which is i
13760 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a nterpreted as.**
13770 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 a boolean in or
13780 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 der to enable or
13790 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 disable the use
137a0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 of covering ind
137b0 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c ices for.** full
137c0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 table scans in
137d0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 the query optimi
137e0 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c zer. The defaul
137f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 t setting is det
13800 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 ermined.** by th
13810 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f e [SQLITE_ALLOW_
13820 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
13830 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CAN] compile-tim
13840 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 e option, or is
13850 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 "on".** if that
13860 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
13870 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ion is omitted..
13880 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 ** The ability t
13890 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 o disable the us
138a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
138b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
138c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 able scans.** is
138d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e because some in
138e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 correctly coded
138f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 legacy applicati
13900 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e ons might malfun
13910 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 ction.** malfunc
13920 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 tion when the op
13930 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e timization is en
13940 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e abled. Providin
13950 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f g the ability to
13960 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 .** disable the
13970 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c optimization all
13980 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 ows the older, b
13990 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e uggy application
139a0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a code to work.**
139b0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 without change
139c0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 even with newer
139d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
139e0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 te..**.** [[SQLI
139f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
13a00 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
13a10 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
13a20 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
13a30 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
13a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13a50 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 PCACHE.** <dd> T
13a60 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 hese options are
13a70 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 obsolete and sh
13a80 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
13a90 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a by new code..**
13aa0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e They are retain
13ab0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
13ac0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 compatibility b
13ad0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 ut are now no-op
13ae0 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a s..** </dl>.**.*
13af0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13b00 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 G_SQLLOG]].** <d
13b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13b20 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 SQLLOG.** <dd>Th
13b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c is option is onl
13b40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 y available if s
13b50 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 qlite is compile
13b60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
13b70 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c LITE_ENABLE_SQLL
13b80 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 OG pre-processor
13b90 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 macro defined.
13ba0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
13bb0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 nt should.** be
13bc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 a pointer to a f
13bd0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
13be0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
13bf0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 lite3*,const cha
13c00 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 r*, int)..** The
13c10 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 second should b
13c20 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a e of type (void*
13c30 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ). The callback
13c40 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 is invoked by th
13c50 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 e library.** in
13c60 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 three separate c
13c70 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 ircumstances, id
13c80 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
13c90 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
13ca0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
13cb0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 rameter. If the
13cc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
13cd0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 is 0, then the
13ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13cf0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 ion.** passed as
13d00 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
13d10 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 ment has just be
13d20 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 en opened. The t
13d30 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
13d40 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 points to a buf
13d50 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 fer containing t
13d60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
13d70 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
13d80 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 e. If the.** fou
13d90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
13da0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 1, then the SQL
13db0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
13dc0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
13dd0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ter.** points to
13de0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 has just been e
13df0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 xecuted. Or, if
13e00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
13e10 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a eter is 2, then.
13e20 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ** the connectio
13e30 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 n being passed a
13e40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
13e50 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 ameter is being
13e60 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 closed. The.** t
13e70 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
13e80 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e s passed NULL In
13e90 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c this case..** <
13ea0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
13eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
13ec0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
13ed0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
13ee0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
13ef0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
13f00 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
13f10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13f20 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
13f30 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
13f40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
13f50 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
13f60 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
13f70 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
13f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
13f90 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
13fa0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
13fb0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
13fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
13fd0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
13fe0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
13ff0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
14000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14010 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
14020 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
14030 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
14040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14050 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
14060 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
14070 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
14080 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
14090 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
140a0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
140b0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
140c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
140d0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
140e0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
140f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
14100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14110 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
14120 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
14130 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
14140 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
14150 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
14160 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
14170 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
14180 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
14190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
141a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
141b0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
141c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
141d0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
141e0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 14 /* no-op *
141f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
14200 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
14210 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f E 15 /* no-o
14220 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
14230 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 ITE_CONFIG_LOG
14240 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 16 /* x
14250 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 Func, void* */.#
14260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14270 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 NFIG_URI
14280 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 17 /* int */.
14290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
142a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 ONFIG_PCACHE2
142b0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 18 /* sqlite
142c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
142d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
142e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
142f0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 CACHE2 19 /*
14300 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
14310 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 ethods2* */.#def
14320 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14330 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
14340 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 _SCAN 20 /* int
14350 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14360 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14370 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 21 /* xS
14380 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a qllog, void* */.
14390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
143a0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
143b0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 tion Configurati
143c0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a on Options.**.**
143d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
143e0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
143f0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
14400 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
14410 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
14420 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
14430 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
14440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
14450 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
14460 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
14470 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14480 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
14490 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
144a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
144b0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
144c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
144d0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
144e0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
144f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
14500 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
14510 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
14520 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
14530 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
14540 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
14550 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b worked. ^The [
14560 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
14570 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
14580 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
14590 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
145a0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
145b0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
145c0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
145d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
145e0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
145f0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
14600 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
14610 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
14620 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
14630 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
14640 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
14650 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
14660 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
14670 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
14680 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
14690 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
146a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
146b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 ]..** ^The first
146c0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 argument (the t
146d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
146e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
146f0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 nfig()] is a.**
14700 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
14710 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
14720 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
14730 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
14740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
14750 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
14760 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
14770 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
14780 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
14790 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
147a0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
147b0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
147c0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
147d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
147e0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
147f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
14800 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
14810 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
14820 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
14830 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
14840 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
14850 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
14860 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
14870 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
14880 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
14890 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
148a0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
148b0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
148c0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
148d0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
148e0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
148f0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
14900 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
14910 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
14920 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
14930 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
14940 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
14950 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
14960 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
14970 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
14980 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
14990 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
149a0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
149b0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
149c0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
149d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
149e0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
149f0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
14a00 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
14a10 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
14a20 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
14a30 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
14a40 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
14a50 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
14a60 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
14a70 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
14a80 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14aa0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
14ab0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
14ac0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
14ad0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
14ae0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
14af0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
14b00 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
14b10 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
14b30 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
14b40 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
14b50 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
14b60 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
14b70 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
14b80 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EY</dt>.** <dd>
14b90 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
14ba0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
14bb0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e r disable the en
14bc0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 forcement of.**
14bd0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e [foreign key con
14be0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 straints]. Ther
14bf0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
14c00 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
14c10 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
14c20 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
14c30 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
14c40 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
14c50 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a FK enforcement,.
14c60 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
14c70 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 nable FK enforce
14c80 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 ment or negative
14c90 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 to leave FK enf
14ca0 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 orcement.** unch
14cb0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f anged. The seco
14cc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
14cd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14ce0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
14cf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
14d00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
14d10 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 ate whether FK e
14d20 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 nforcement is of
14d30 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f f or on.** follo
14d40 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
14d50 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
14d60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
14d70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
14d80 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
14d90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
14da0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
14db0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
14dc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
14dd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
14de0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 NABLE_TRIGGER</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
14e00 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
14e10 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
14e20 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 able [CREATE TRI
14e30 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d GGER | triggers]
14e40 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c ..** There shoul
14e50 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
14e60 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
14e70 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
14e80 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
14e90 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
14ea0 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 disable trigger
14eb0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 s,.** positive t
14ec0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 o enable trigger
14ed0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f s or negative to
14ee0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
14ef0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a ng unchanged..**
14f00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
14f10 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
14f20 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
14f30 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
14f40 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
14f50 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
14f60 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 ther triggers ar
14f70 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e e disabled or en
14f80 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 abled.** followi
14f90 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
14fa0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
14fb0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
14fc0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
14fd0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
14fe0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 trigger setting
14ff0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
15000 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
15010 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
15020 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
15030 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
15040 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 1001 /* void
15050 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 * int int */.#de
15060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
15070 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 NFIG_ENABLE_FKEY
15080 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 1002 /* in
15090 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
150a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
150b0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
150c0 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 1003 /* int i
150d0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt* */.../*.** C
150e0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
150f0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
15100 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
15110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
15120 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
15130 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 ult_codes() rout
15140 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
15150 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b isables the.** [
15160 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
15170 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f codes] feature o
15180 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 f SQLite. ^The e
15190 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
151a0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 * codes are disa
151b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
151c0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 for historical c
151d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f ompatibility..*/
151e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 .int sqlite3_ext
151f0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
15200 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
15210 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
15220 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
15230 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a nsert Rowid.**.*
15240 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e * ^Each entry in
15250 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 an SQLite table
15260 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 has a unique 64
15270 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 -bit signed.** i
15280 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 nteger key calle
15290 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 d the [ROWID | "
152a0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f rowid"]. ^The ro
152b0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 wid is always av
152c0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e ailable.** as an
152d0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 undeclared colu
152e0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 mn named ROWID,
152f0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 OID, or _ROWID_
15300 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 as long as those
15310 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f .** names are no
15320 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 t also used by e
15330 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
15340 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a ed columns. ^If.
15350 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 ** the table has
15360 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 a column of typ
15370 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 e [INTEGER PRIMA
15380 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 RY KEY] then tha
15390 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
153a0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
153b0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
153c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
153d0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 returns the [row
153e0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 id] of the most
153f0 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 recent.** succes
15400 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e sful [INSERT] in
15410 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
15420 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 from the [databa
15430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
15440 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
15450 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 rgument. ^As of
15460 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
15470 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 3.7.7, this rout
15480 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 ines.** records
15490 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
154a0 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 rowid of both or
154b0 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e dinary tables an
154c0 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 d [virtual table
154d0 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 s]..** ^If no su
154e0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
154f0 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 ]s.** have ever
15500 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 occurred on that
15510 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15520 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 tion, zero is re
15530 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 turned..**.** ^(
15540 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f If an [INSERT] o
15550 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 ccurs within a t
15560 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e rigger or within
15570 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
15580 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 e].** method, th
15590 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
155a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
155b0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
155c0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 nserted.** row a
155d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
155e0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
155f0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 table method is
15600 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
15610 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
15620 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 r or virtual tab
15630 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 le method ends,
15640 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
15650 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
15660 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
15670 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
15680 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
15690 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 or virtual.** t
156a0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 able method bega
156b0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b n.)^.**.** ^An [
156c0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 INSERT] that fai
156d0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 ls due to a cons
156e0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
156f0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 is not a.** suc
15700 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
15710 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 and does not ch
15720 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 ange the value r
15730 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a eturned by this.
15740 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 ** routine. ^Th
15750 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
15760 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
15770 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
15780 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
15790 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
157a0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
157b0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
157c0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
157d0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
157e0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
157f0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 s. ^(When INSER
15800 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 T OR REPLACE.**
15810 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e encounters a con
15820 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
15830 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 n, it does not f
15840 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 ail. The.** INS
15850 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f ERT continues to
15860 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 completion afte
15870 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 r deleting rows
15880 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 that caused.** t
15890 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 he constraint pr
158a0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 oblem so INSERT
158b0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 OR REPLACE will
158c0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a always change.**
158d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
158e0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
158f0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f ace.)^.**.** ^Fo
15900 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
15910 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
15920 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 an [INSERT] is c
15930 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 onsidered to.**
15940 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 be successful ev
15950 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 en if it is subs
15960 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 equently rolled
15970 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 back..**.** This
15980 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 function is acc
15990 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 essible to SQL s
159a0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 tatements via th
159b0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 e.** [last_inser
159c0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 t_rowid() SQL fu
159d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
159e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
159f0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e ead performs a n
15a00 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 ew [INSERT] on t
15a10 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 he same.** datab
15a20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
15a30 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 hile the [sqlite
15a40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
15a50 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 wid()].** functi
15a60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e on is running an
15a70 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 d thus changes t
15a80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b he last insert [
15a90 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 rowid],.** then
15aa0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
15ab0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
15ac0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
15ad0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 ()] is.** unpred
15ae0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 ictable and migh
15af0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 t not equal eith
15b00 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 er the old or th
15b10 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e e new.** last in
15b20 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f sert [rowid]..*/
15b30 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
15b40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
15b50 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
15b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
15b70 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
15b80 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
15b90 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
15ba0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
15bb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
15bc0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
15bd0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
15be0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
15bf0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
15c00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
15c10 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
15c20 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
15c30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
15c40 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
15c50 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
15c60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 parameter..** ^(
15c70 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
15c80 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
15c90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
15ca0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
15cb0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
15cc0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
15cd0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
15ce0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
15cf0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
15d00 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b rs or [foreign k
15d10 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
15d20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 not counted.)^ U
15d30 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 se the.** [sqlit
15d40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
15d50 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ()] function to
15d60 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
15d70 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
15d80 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 .** including ch
15d90 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
15da0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 triggers and for
15db0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
15dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 ..**.** ^Changes
15dd0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
15de0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 are simulated by
15df0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
15e00 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 trigger].** are
15e10 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e not counted. On
15e20 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 ly real table ch
15e30 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
15e40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f d..**.** ^(A "ro
15e50 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
15e60 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
15e70 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
15e80 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
15e90 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
15ea0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
15eb0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
15ec0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
15ed0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
15ee0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 ffects of [REPLA
15ef0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
15f00 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
15f10 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
15f20 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 ocessing, [DROP
15f30 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e TABLE], or by an
15f40 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 y other.** mecha
15f50 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 nisms do not cou
15f60 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 nt as direct row
15f70 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a changes.)^.**.*
15f80 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
15f90 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
15fa0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
15fb0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
15fc0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
15fd0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 cript of a [CREA
15fe0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
15ff0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 gger]. .** Most
16000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
16010 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
16020 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
16030 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
16040 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
16050 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
16060 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
16070 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
16080 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
16090 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
160a0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
160b0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
160c0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
160d0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
160e0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
160f0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
16100 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
16110 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 .** ^Calling [sq
16120 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
16130 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
16140 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
16150 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
16160 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
16170 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ontext..**.** ^T
16180 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
16190 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
161a0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 of direct row ch
161b0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 anges in the.**
161c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
161d0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
161e0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
161f0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a within the same.
16200 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
16210 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c xt..**.** ^Thus,
16220 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
16230 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
16240 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
16250 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
16260 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
16270 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
16280 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
16290 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
162a0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
162b0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
162c0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 vel. ^(Within t
162d0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 he body of a tri
162e0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c gger,.** the sql
162f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 ite3_changes() i
16300 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
16310 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 called to find t
16320 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
16330 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
16340 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
16350 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
16360 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
16370 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 .** statement wi
16380 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
16390 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
163a0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 r..** However, t
163b0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e he number return
163c0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
163d0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 ude changes.** c
163e0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 aused by subtrig
163f0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 gers since those
16400 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 have their own
16410 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a context.)^.**.**
16420 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
16430 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
16440 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
16450 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
16460 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
16470 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
16480 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
16490 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
164a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
164b0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
164c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
164d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
164e0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
164f0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
16500 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
16510 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
16520 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
16530 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
16540 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ful..*/.int sqli
16550 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 te3_changes(sqli
16560 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
16570 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 PI3REF: Total Nu
16580 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
16590 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ified.**.** ^Thi
165a0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
165b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
165c0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 row changes cau
165d0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c sed by [INSERT],
165e0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 .** [UPDATE] or
165f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
16600 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
16610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16620 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
16630 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 ** ^(The count r
16640 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
16650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
16660 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
16670 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 changes.** from
16680 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 all [CREATE TRIG
16690 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 GER | trigger] c
166a0 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e ontexts and chan
166b0 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b ges made by.** [
166c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
166d0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a ons]. However,.*
166e0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 * the count does
166f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
16700 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 nges used to imp
16710 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d lement [REPLACE]
16720 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a constraints,.**
16730 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 do rollbacks or
16740 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
16750 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c g, or [DROP TABL
16760 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 E] processing.
16770 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 The.** count doe
16780 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f s not include ro
16790 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 ws of views that
167a0 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 fire an [INSTEA
167b0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a D OF trigger],.*
167c0 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 * though if the
167d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
167e0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 er makes changes
167f0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f of its own, tho
16800 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 se changes .** a
16810 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a re counted.)^.**
16820 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f ^The sqlite3_to
16830 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 tal_changes() fu
16840 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 nction counts th
16850 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f e changes as soo
16860 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 n as.** the stat
16870 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 ement that makes
16880 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 them is complet
16890 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 ed (when the sta
168a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a tement handle.**
168b0 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 is passed to [s
168c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
168d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
168e0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 lize()])..**.**
168f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
16900 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
16910 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
16920 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
16930 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
16940 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 he [total_change
16950 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
16960 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
16970 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
16980 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
16990 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
169a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
169b0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f hile [sqlite3_to
169c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
169d0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
169e0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
169f0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 rned is unpredic
16a00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
16a10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 aningful..*/.int
16a20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
16a30 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
16a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
16a50 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c F: Interrupt A L
16a60 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 ong-Running Quer
16a70 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 y.**.** ^This fu
16a80 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
16a90 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
16aa0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
16ab0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
16ac0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
16ad0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
16ae0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
16af0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
16b00 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
16b10 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
16b20 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
16b30 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
16b40 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
16b50 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
16b60 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
16b70 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
16b80 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
16b90 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 ** ^It is safe t
16ba0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
16bb0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 ine from a threa
16bc0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d d different from
16bd0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 the.** thread t
16be0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 hat is currently
16bf0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 running the dat
16c00 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e abase operation.
16c10 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e But it.** is n
16c20 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 ot safe to call
16c30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
16c40 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
16c50 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a nnection] that.*
16c60 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d * is closed or m
16c70 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 ight close befor
16c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
16c90 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a upt() returns..*
16ca0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 *.** ^If an SQL
16cb0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 operation is ver
16cc0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 y nearly finishe
16cd0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 d at the time wh
16ce0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e en.** sqlite3_in
16cf0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c terrupt() is cal
16d00 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 led, then it mig
16d10 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f ht not have an o
16d20 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f pportunity.** to
16d30 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 be interrupted
16d40 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e and might contin
16d50 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e ue to completion
16d60 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 ..**.** ^An SQL
16d70 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 operation that i
16d80 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 s interrupted wi
16d90 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
16da0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a E_INTERRUPT]..**
16db0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 ^If the interru
16dc0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 pted SQL operati
16dd0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c on is an INSERT,
16de0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
16df0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e TE.** that is in
16e00 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 side an explicit
16e10 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
16e20 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 en the entire tr
16e30 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c ansaction.** wil
16e40 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b l be rolled back
16e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a automatically..
16e60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
16e70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
16e80 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 call is in effec
16e90 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 t until all curr
16ea0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a ently running.**
16eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
16ec0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
16ed0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c nection] D compl
16ee0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 ete. ^Any new S
16ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
16f00 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
16f10 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
16f20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
16f30 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 call and before
16f40 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 the .** running
16f50 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 statements reach
16f60 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 es zero are inte
16f70 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 rrupted as if th
16f80 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 ey had been.** r
16f90 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 unning prior to
16fa0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
16fb0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e rrupt() call. ^
16fc0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e New SQL statemen
16fd0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
16fe0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
16ff0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 running stateme
17000 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 nt count reaches
17010 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 zero are.** not
17020 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 effected by the
17030 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
17040 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c pt()..** ^A call
17050 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 to sqlite3_inte
17060 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 rrupt(D) that oc
17070 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 curs when there
17080 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a are no running.*
17090 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
170a0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 is a no-op and
170b0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e has no effect on
170c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
170d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
170e0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
170f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
17100 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a ) call returns..
17110 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 **.** If the dat
17120 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17130 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 closes while [s
17140 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
17150 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e ()].** is runnin
17160 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 g then bad thing
17170 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 s will likely ha
17180 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 ppen..*/.void sq
17190 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
171a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
171b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
171c0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
171d0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d Statement Is Com
171e0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 plete.**.** Thes
171f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
17200 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d seful during com
17210 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
17220 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
17230 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
17240 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
17250 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f ems to form a co
17260 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
17270 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
17280 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
17290 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
172a0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
172b0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
172c0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 for parsing. ^T
172d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
172e0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e turn 1 if the in
172f0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 put string.** ap
17300 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f pears to be a co
17310 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
17320 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d ment. ^A statem
17330 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f ent is judged to
17340 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 be.** complete
17350 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 if it ends with
17360 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 a semicolon toke
17370 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 n and is not a p
17380 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 refix of a.** we
17390 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 ll-formed CREATE
173a0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 TRIGGER stateme
173b0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 nt. ^Semicolons
173c0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 that are embedd
173d0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 ed within.** str
173e0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 ing literals or
173f0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 quoted identifie
17400 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 r names or comme
17410 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 nts are not.** i
17420 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e ndependent token
17430 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 s (they are part
17440 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e of the token in
17450 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a which they are.
17460 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 ** embedded) and
17470 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 thus do not cou
17480 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e nt as a statemen
17490 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e t terminator. ^
174a0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e Whitespace.** an
174b0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 d comments that
174c0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c follow the final
174d0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 semicolon are i
174e0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gnored..**.** ^T
174f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
17500 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 turn 0 if the st
17510 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d atement is incom
17520 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a plete. ^If a.**
17530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
17540 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 on fails, then S
17550 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 QLITE_NOMEM is r
17560 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
17570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 These routines d
17580 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 o not parse the
17590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 SQL statements t
175a0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 hus.** will not
175b0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 detect syntactic
175c0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 ally incorrect S
175d0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 QL..**.** ^(If S
175e0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 QLite has not be
175f0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 en initialized u
17600 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e sing [sqlite3_in
17610 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f itialize()] prio
17620 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e r .** to invokin
17630 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 g sqlite3_comple
17640 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 te16() then sqli
17650 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
17660 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
17670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
17680 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
17690 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 16(). If that i
176a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 nitialization fa
176b0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ils,.** then the
176c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
176d0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c om sqlite3_compl
176e0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 ete16() will be
176f0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 non-zero.** rega
17700 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
17710 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 r or not the inp
17720 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 ut SQL is comple
17730 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te.)^.**.** The
17740 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
17750 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 3_complete()] mu
17760 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
17770 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 minated.** UTF-8
17780 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
17790 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
177a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
177b0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
177c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
177d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
177e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
177f0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 er..*/.int sqlit
17800 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 e3_complete(cons
17810 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e t char *sql);.in
17820 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
17830 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
17840 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
17850 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
17860 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
17870 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
17880 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e Y Errors.**.** ^
17890 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
178a0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
178b0 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 ction that might
178c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
178d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
178e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 pt is made to op
178f0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 en a database ta
17900 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 ble that another
17910 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
17920 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 ocess has locked
17930 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
17940 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
17950 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c NULL, then [SQL
17960 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
17970 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
17980 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ED].** is return
17990 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 ed immediately u
179a0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 pon encountering
179b0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 the lock. ^If
179c0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
179d0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c k.** is not NULL
179e0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 , then the callb
179f0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 ack might be inv
17a00 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 oked with two ar
17a10 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e guments..**.** ^
17a20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
17a30 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 nt to the busy h
17a40 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 andler is a copy
17a50 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f of the void* po
17a60 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 inter which.** i
17a70 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
17a80 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
17a90 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 busy_handler().
17aa0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ^The second arg
17ab0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 ument to.** the
17ac0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c busy handler cal
17ad0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d lback is the num
17ae0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
17af0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c t the busy handl
17b00 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 er has.** been i
17b10 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 nvoked for this
17b20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
17b30 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 ^If the.** busy
17b40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
17b50 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
17b60 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
17b70 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
17b80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
17b90 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
17ba0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
17bb0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
17bc0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e s returned..** ^
17bd0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
17be0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
17bf0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 , then another a
17c00 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 ttempt.** is mad
17c10 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
17c20 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 tabase for readi
17c30 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 ng and the cycle
17c40 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
17c50 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
17c60 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
17c70 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
17c80 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
17c90 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
17ca0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
17cb0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 contention. ^If
17cc0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
17cd0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
17ce0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
17cf0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
17d00 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
17d10 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
17d20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
17d30 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 ITE_BUSY].** or
17d40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
17d50 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f OCKED] instead o
17d60 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 f invoking the b
17d70 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 usy handler..**
17d80 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 Consider a scena
17d90 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 rio where one pr
17da0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
17db0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 a read lock tha
17dc0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e t.** it is tryin
17dd0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 g to promote to
17de0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
17df0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 and.** a second
17e00 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
17e10 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f ng a reserved lo
17e20 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 ck that it is tr
17e30 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f ying.** to promo
17e40 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 te to an exclusi
17e50 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 ve lock. The fi
17e60 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e rst process cann
17e70 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 ot proceed.** be
17e80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
17e90 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ked by the secon
17ea0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 d and the second
17eb0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a process cannot.
17ec0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 ** proceed becau
17ed0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
17ee0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 by the first.
17ef0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 If both processe
17f00 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 s.** invoke the
17f10 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e busy handlers, n
17f20 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 either will make
17f30 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 any progress.
17f40 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 Therefore,.** SQ
17f50 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 Lite returns [SQ
17f60 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 LITE_BUSY] for t
17f70 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
17f80 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 , hoping that th
17f90 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 is.** will induc
17fa0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 e the first proc
17fb0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 ess to release i
17fc0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 ts read lock and
17fd0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 allow.** the se
17fe0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 cond process to
17ff0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e proceed..**.** ^
18000 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 The default busy
18010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
18020 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 L..**.** ^The [S
18030 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f QLITE_BUSY] erro
18040 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 r is converted t
18050 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f o [SQLITE_IOERR_
18060 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e BLOCKED].** when
18070 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 SQLite is in th
18080 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 e middle of a la
18090 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 rge transaction
180a0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a where all the.**
180b0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f changes will no
180c0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 t fit into the i
180d0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 n-memory cache.
180e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
180f0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 already hold a R
18100 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 ESERVED lock on
18110 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
18120 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a e, but it needs.
18130 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 ** to promote th
18140 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 is lock to EXCLU
18150 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 SIVE so that it
18160 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a can spill cache.
18170 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 ** pages into th
18180 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
18190 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 without harm to
181a0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 concurrent.** re
181b0 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 aders. ^If it i
181c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d s unable to prom
181d0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 ote the lock, th
181e0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 en the in-memory
181f0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 .** cache will b
18200 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 e left in an inc
18210 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 onsistent state
18220 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 and so the error
18230 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d .** code is prom
18240 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 oted from the re
18250 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 latively benign
18260 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f [SQLITE_BUSY] to
18270 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 .** the more sev
18280 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 ere [SQLITE_IOER
18290 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 R_BLOCKED]. ^Th
182a0 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 is error code pr
182b0 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 omotion.** force
182c0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 s an automatic r
182d0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 ollback of the c
182e0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 hanges. See the
182f0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 .** <a href="/cv
18300 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 strac/wiki?p=Cor
18310 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
18320 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 BusyError">.** C
18330 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
18340 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 ngBusyError</a>
18350 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 wiki page for a
18360 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 discussion of wh
18370 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 y.** this is imp
18380 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ortant..**.** ^(
18390 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
183a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
183b0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 handler defined
183c0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 for each.** [dat
183d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
183e0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 ]. Setting a ne
183f0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 w busy handler c
18400 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 lears any.** pre
18410 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 viously set hand
18420 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 ler.)^ ^Note th
18430 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
18440 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
18450 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
18460 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
18470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
18480 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
18490 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
184a0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
184b0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
184c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
184d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
184e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
184f0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
18500 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
18510 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
18520 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
18530 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
18540 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
18550 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
18560 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
18570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
18580 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
18590 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
185a0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ler..*/.int sqli
185b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
185c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
185d0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f )(void*,int), vo
185e0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
185f0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 I3REF: Set A Bus
18600 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 y Timeout.**.**
18610 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 ^This routine se
18620 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 ts a [sqlite3_bu
18630 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 sy_handler | bus
18640 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 y handler] that
18650 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 sleeps.** for a
18660 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 specified amount
18670 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 of time when a
18680 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e table is locked.
18690 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a ^The handler.*
186a0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c * will sleep mul
186b0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 tiple times unti
186c0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 l at least "ms"
186d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
186e0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 sleeping.** have
186f0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e accumulated. ^
18700 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 After at least "
18710 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
18720 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a of sleeping,.**
18730 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 the handler ret
18740 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 urns 0 which cau
18750 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ses [sqlite3_ste
18760 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a p()] to return.*
18770 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 * [SQLITE_BUSY]
18780 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
18790 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a _BLOCKED]..**.**
187a0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 ^Calling this r
187b0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 outine with an a
187c0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 rgument less tha
187d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
187e0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 ro.** turns off
187f0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 all busy handler
18800 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 s..**.** ^(There
18810 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
18820 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
18830 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 er for a particu
18840 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
18850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 connection] any
18860 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
18870 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
18880 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
18890 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
188a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
188b0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
188c0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
188d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
188e0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
188f0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
18900 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 d.)^.*/.int sqli
18910 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
18920 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d (sqlite3*, int m
18930 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
18940 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 REF: Convenience
18950 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 Routines For Ru
18960 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a nning Queries.**
18970 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 .** This is a le
18980 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 gacy interface t
18990 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 hat is preserved
189a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
189b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
189c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 Use of this int
189d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
189e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
189f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c Definition: A <
18a00 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f b>result table</
18a10 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 b> is memory dat
18a20 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 a structure crea
18a30 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 ted by the.** [s
18a40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
18a50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
18a60 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 A result table r
18a70 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f ecords the.** co
18a80 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 mplete query res
18a90 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 ults from one or
18aa0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a more queries..*
18ab0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 *.** The table c
18ac0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 onceptually has
18ad0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 a number of rows
18ae0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 and columns. B
18af0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 ut.** these numb
18b00 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 ers are not part
18b10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 of the result t
18b20 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 able itself. Th
18b30 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 ese.** numbers a
18b40 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 re obtained sepa
18b50 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 rately. Let N b
18b60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
18b70 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 rows.** and M be
18b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
18b90 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 olumns..**.** A
18ba0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
18bb0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
18bc0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 ters to zero-ter
18bd0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
18be0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 rings..** There
18bf0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d are (N+1)*M elem
18c00 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 ents in the arra
18c10 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 y. The first M
18c20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a pointers point.*
18c30 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e * to zero-termin
18c40 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
18c50 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e t contain the n
18c60 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ames of the colu
18c70 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 mns..** The rema
18c80 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c ining entries al
18c90 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 l point to query
18ca0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 results. NULL
18cb0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a values result.**
18cc0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 in NULL pointer
18cd0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 s. All other va
18ce0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 lues are in thei
18cf0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 r UTF-8 zero-ter
18d00 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
18d10 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e g representation
18d20 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 as returned by
18d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
18d40 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 text()]..**.** A
18d50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 result table mi
18d60 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f ght consist of o
18d70 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 ne or more memor
18d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a y allocations..*
18d90 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
18da0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c to pass a resul
18db0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 t table directly
18dc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
18dd0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c e()]..** A resul
18de0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 t table should b
18df0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 e deallocated us
18e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
18e10 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a e_table()]..**.*
18e20 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c * ^(As an exampl
18e30 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 e of the result
18e40 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 table format, su
18e50 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 ppose a query re
18e60 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f sult.** is as fo
18e70 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
18e80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
18e90 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 * Name
18ea0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 | Age.**
18eb0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -----------
18ec0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 ------------.**
18ed0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 Alice
18ee0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 | 43.**
18ef0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 Bob |
18f00 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 28.** Cin
18f10 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a dy | 21.**
18f20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
18f30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ote>.**.** There
18f40 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 are two column
18f50 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 (M==2) and three
18f60 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 rows (N==3). T
18f70 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c hus the.** resul
18f80 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e t table has 8 en
18f90 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 tries. Suppose
18fa0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
18fb0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e is stored.** in
18fc0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 an array names
18fd0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 azResult. Then
18fe0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 azResult holds t
18ff0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a his content:.**.
19000 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
19010 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 pre>.** a
19020 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d zResult[0] =
19030 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 "Name";.**
19040 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
19050 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
19060 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
19070 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 91;2] = "Alice";
19080 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
19090 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 ult[3] = "43
190a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
190b0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 esult[4] = "
190c0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Bob";.**
190d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 azResult[5]
190e0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
190f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 azResult[6
19100 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 ] = "Cindy";.**
19110 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
19120 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a #91;7] = "21";.*
19130 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
19140 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 uote>)^.**.** ^T
19150 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
19160 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 able() function
19170 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 evaluates one or
19180 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c more.** semicol
19190 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c on-separated SQL
191a0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
191b0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
191c0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 ed UTF-8.** stri
191d0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 ng of its 2nd pa
191e0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 rameter and retu
191f0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 rns a result tab
19200 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 le to the.** poi
19210 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 nter given in it
19220 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e s 3rd parameter.
19230 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
19240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 application has
19250 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 finished with t
19260 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 he result from s
19270 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
19280 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 (),.** it must p
19290 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 ass the result t
192a0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 able pointer to
192b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
192c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
192d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
192e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
192f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
19300 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
19310 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
19320 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
19330 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
19340 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
19350 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
19360 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
19370 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
19380 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
19390 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
193a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
193b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
193c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
193d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
193e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
193f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
19400 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
19410 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
19420 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
19430 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
19440 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
19450 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
19460 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
19470 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
19480 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
19490 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
194a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
194b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
194c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
194d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
194e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
194f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
19500 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
19510 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
19520 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
19530 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
19540 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
19550 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
19560 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
19570 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
19580 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 rrcode()] or.**
19590 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
195a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
195b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
195c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
195d0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
195e0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
195f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
19600 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
19610 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
19620 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
19630 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
19640 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
19650 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
19660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
19670 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
19680 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
19690 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
196a0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
196b0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
196c0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
196d0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
196e0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
196f0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
19700 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
19710 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
19720 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
19730 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
19740 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
19750 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
19760 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a g Functions.**.*
19770 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
19780 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 are work-alikes
19790 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 of the "printf(
197a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e )" family of fun
197b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 ctions.** from t
197c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
197d0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 brary..**.** ^Th
197e0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 e sqlite3_mprint
197f0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f f() and sqlite3_
19800 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 vmprintf() routi
19810 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a nes write their.
19820 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 ** results into
19830 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
19840 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
19850 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lloc()]..** The
19860 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
19870 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f by these two ro
19880 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 utines should be
19890 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 .** released by
198a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
198b0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 . ^Both routine
198c0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
198d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
198e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
198f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
19900 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
19910 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
19920 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
19930 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ring..**.** ^(Th
19940 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e e sqlite3_snprin
19950 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
19960 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
19970 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
19980 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
19990 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
199a0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
199b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
199c0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
199d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
199e0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
199f0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
19a00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
19a10 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
19a20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
19a30 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
19a40 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
19a50 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
19a60 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a .)^ This is an.
19a70 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
19a80 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
19a90 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
19aa0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
19ab0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
19ac0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 ibility. ^(Note
19ad0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
19ae0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
19af0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
19b00 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
19b10 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
19b20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
19b30 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
19b40 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
19b50 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 e buffer.)^ We
19b60 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
19b70 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
19b80 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
19b90 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
19ba0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
19bb0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
19bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
19bd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
19be0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
19bf0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
19c00 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
19c10 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
19c20 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ^As long as the
19c30 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 buffer size is
19c40 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
19c50 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 o, sqlite3_snpri
19c60 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 ntf().** guarant
19c70 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 ees that the buf
19c80 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 fer is always ze
19c90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
19ca0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 ^The first.** pa
19cb0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
19cc0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
19cd0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
19ce0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
19cf0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
19d00 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
19d10 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
19d20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
19d30 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
19d40 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
19d50 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
19d60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e ^The sqlite3_vsn
19d70 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
19d80 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 is a varargs ve
19d90 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 rsion of sqlite3
19da0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a _snprintf()..**.
19db0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
19dc0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 s all implement
19dd0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
19de0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 formatting.** op
19df0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 tions that are u
19e00 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 seful for constr
19e10 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 ucting SQL state
19e20 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 ments..** All of
19e30 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 the usual print
19e40 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f f() formatting o
19e50 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 ptions apply. I
19e60 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 n addition, ther
19e70 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 e.** is are "%q"
19e80 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 , "%Q", and "%z"
19e90 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 options..**.**
19ea0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 ^(The %q option
19eb0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
19ec0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
19ed0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 utes a nul-termi
19ee0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
19ef0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
19f00 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 t list. But %q
19f10 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 also doubles eve
19f20 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 ry '\'' characte
19f30 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 r..** %q is desi
19f40 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 gned for use ins
19f50 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 ide a string lit
19f60 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 eral.)^ By doub
19f70 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a ling each '\''.*
19f80 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 * character it e
19f90 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 scapes that char
19fa0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 acter and allows
19fb0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 it to be insert
19fc0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 ed into.** the s
19fd0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 tring..**.** For
19fe0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 example, assume
19ff0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 the string vari
1a000 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 able zText conta
1a010 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c ins text as foll
1a020 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1a030 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1a040 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 char *zText = "
1a050 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1a060 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !";.** </pre></b
1a070 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1a080 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 One can use thi
1a090 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c s text in an SQL
1a0a0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f statement as fo
1a0b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1a0c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1a0d0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1a0e0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1a0f0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1a100 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 le VALUES('%q')"
1a110 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
1a120 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
1a130 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
1a140 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
1a150 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
1a160 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1a170 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 .** Because the
1a180 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 %q format string
1a190 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c is used, the '\
1a1a0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 '' character in
1a1b0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 zText.** is esca
1a1c0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 ped and the SQL
1a1d0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 generated is as
1a1e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1a1f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1a200 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1a210 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1a220 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 It''s a happy da
1a230 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!').** </pre></
1a240 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1a250 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 * This is correc
1a260 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 t. Had we used
1a270 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 %s instead of %q
1a280 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 , the generated
1a290 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 SQL.** would hav
1a2a0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 e looked like th
1a2b0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b is:.**.** <block
1a2c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1a2d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1a2e0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 e1 VALUES('It's
1a2f0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a a happy day!');.
1a300 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1a310 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1a320 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 s second example
1a330 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 is an SQL synta
1a340 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 x error. As a g
1a350 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 eneral rule you
1a360 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 should.** always
1a370 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 use %q instead
1a380 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 of %s when inser
1a390 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 ting text into a
1a3a0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1a3b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 .**.** ^(The %Q
1a3c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1a3d0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 e %q except it a
1a3e0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 lso adds single
1a3f0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a quotes around.**
1a400 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 the outside of
1a410 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 the total string
1a420 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c . Additionally,
1a430 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1a440 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 r in the.** argu
1a450 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e ment list is a N
1a460 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 ULL pointer, %Q
1a470 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 substitutes the
1a480 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 text "NULL" (wit
1a490 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 hout.** single q
1a4a0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 uotes).)^ So, f
1a4b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 or example, one
1a4c0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a could say:.**.**
1a4d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1a4e0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
1a4f0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
1a500 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
1a510 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 table VALUES(%Q
1a520 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1a530 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1a540 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1a550 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1a560 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1a570 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1a580 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 **.** The code a
1a590 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 bove will render
1a5a0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 a correct SQL s
1a5b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
1a5c0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 zSQL.** variable
1a5d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 even if the zTe
1a5e0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 xt variable is a
1a5f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1a600 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 *.** ^(The "%z"
1a610 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1a620 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 n works like "%s
1a630 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a " but with the.*
1a640 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
1a650 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
1a660 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
1a670 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
1a680 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
1a690 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
1a6a0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
1a6b0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a input string.)^.
1a6c0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 */.char *sqlite3
1a6d0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 _mprintf(const c
1a6e0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 har*,...);.char
1a6f0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 *sqlite3_vmprint
1a700 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
1a710 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 a_list);.char *s
1a720 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1a730 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1a740 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 char*, ...);.cha
1a750 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 r *sqlite3_vsnpr
1a760 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
1a770 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
1a780 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ist);../*.** CAP
1a790 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
1a7a0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 location Subsyst
1a7b0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c em.**.** The SQL
1a7c0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 ite core uses th
1a7d0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e ese three routin
1a7e0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 es for all of it
1a7f0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 s own.** interna
1a800 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
1a810 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 ion needs. "Core
1a820 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 " in the previou
1a830 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f s sentence.** do
1a840 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f es not include o
1a850 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
1a860 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 specific VFS imp
1a870 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 lementation. Th
1a880 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 e.** Windows VFS
1a890 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c uses native mal
1a8a0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
1a8b0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 for some operat
1a8c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions..**.** ^The
1a8d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1a8e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
1a8f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1a900 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d block.** of mem
1a910 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 ory at least N b
1a920 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 ytes in length,
1a930 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 where N is the p
1a940 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
1a950 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1a960 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
1a970 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
1a980 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
1a990 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
1a9a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 LL pointer. ^If
1a9b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e the parameter N
1a9c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d to.** sqlite3_m
1a9d0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
1a9e0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e or negative then
1a9f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1aa00 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e ) returns.** a N
1aa10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
1aa20 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
1aa30 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
1aa40 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
1aa50 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
1aa60 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
1aa70 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1aa80 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
1aa90 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
1aaa0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
1aab0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e ht be reused. ^
1aac0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 The sqlite3_free
1aad0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a () routine is.**
1aae0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 a no-op if is c
1aaf0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
1ab00 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 L pointer. Pass
1ab10 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
1ab20 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 er.** to sqlite3
1ab30 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c _free() is harml
1ab40 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e ess. After bein
1ab50 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a g freed, memory.
1ab60 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 ** should neithe
1ab70 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 r be read nor wr
1ab80 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 itten. Even rea
1ab90 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 ding previously
1aba0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 freed.** memory
1abb0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 might result in
1abc0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1abd0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 ault or other se
1abe0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d vere error..** M
1abf0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e emory corruption
1ac00 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e , a segmentation
1ac10 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 fault, or other
1ac20 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a severe error.**
1ac30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 might result if
1ac40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1ac50 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1ac60 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
1ac70 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f r that.** was no
1ac80 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 t obtained from
1ac90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1aca0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
1acb0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 loc()..**.** ^(T
1acc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1acd0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 oc() interface a
1ace0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a ttempts to resiz
1acf0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d e a.** prior mem
1ad00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
1ad10 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 o be at least N
1ad20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 bytes, where N i
1ad30 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 s the.** second
1ad40 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
1ad50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1ad60 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 n to be resized
1ad70 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
1ad80 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 parameter.)^ ^ I
1ad90 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 f the first para
1ada0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1adb0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 _realloc().** is
1adc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1add0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f then its behavio
1ade0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 r is identical t
1adf0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c o calling.** sql
1ae00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 ite3_malloc(N) w
1ae10 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1ae20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
1ae30 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1ae40 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 c()..** ^If the
1ae50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1ae60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
1ae70 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
1ae80 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 .** negative the
1ae90 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
1aea0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
1aeb0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a me as calling.**
1aec0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 sqlite3_free(P)
1aed0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 where P is the
1aee0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1aef0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1af00 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 oc()..** ^sqlite
1af10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
1af20 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1af30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1af40 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1af50 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1af60 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 ize or NULL if s
1af70 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
1af80 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
1af90 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1afa0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
1afb0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
1afc0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
1afd0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
1afe0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
1aff0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
1b000 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
1b010 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
1b020 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
1b030 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 lloc() and the p
1b040 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1b050 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 is freed..** ^If
1b060 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1b070 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c () returns NULL,
1b080 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 then the prior
1b090 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 allocation.** is
1b0a0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
1b0b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 * ^The memory re
1b0c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1b0d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 3_malloc() and s
1b0e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1b0f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c .** is always al
1b100 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 igned to at leas
1b110 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e t an 8 byte boun
1b120 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a dary, or to a.**
1b130 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 4 byte boundary
1b140 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1b150 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 4_BYTE_ALIGNED_M
1b160 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 ALLOC] compile-t
1b170 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 ime.** option is
1b180 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 used..**.** In
1b190 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1b1a0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 .5.0 and 3.5.1,
1b1b0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 it was possible
1b1c0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 to define.** the
1b1d0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d SQLITE_OMIT_MEM
1b1e0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 ORY_ALLOCATION w
1b1f0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 hich would cause
1b200 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a the built-in.**
1b210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1b220 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1b230 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e s to be omitted.
1b240 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 That capabilit
1b250 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 y.** is no longe
1b260 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c r provided. Onl
1b270 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 y built-in memor
1b280 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e y allocators can
1b290 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 be used..**.**
1b2a0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 Prior to SQLite
1b2b0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 version 3.7.10,
1b2c0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 the Windows OS i
1b2d0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 nterface layer c
1b2e0 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 alled.** the sys
1b2f0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 tem malloc() and
1b300 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 free() directly
1b310 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 when converting
1b320 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 .** filenames be
1b330 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 tween the UTF-8
1b340 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 encoding used by
1b350 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 SQLite.** and w
1b360 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 hatever filename
1b370 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
1b380 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 d by the particu
1b390 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 lar Windows.** i
1b3a0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 nstallation. Me
1b3b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1b3c0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 errors were dete
1b3d0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 cted, but.** the
1b3e0 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 y were reported
1b3f0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f back as [SQLITE_
1b400 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 CANTOPEN] or.**
1b410 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 [SQLITE_IOERR] r
1b420 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 ather than [SQLI
1b430 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
1b440 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 The pointer arg
1b450 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 uments to [sqlit
1b460 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b e3_free()] and [
1b470 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1b480 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
1b490 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 ther NULL or els
1b4a0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 e pointers obtai
1b4b0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 ned from a prior
1b4c0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f .** invocation o
1b4d0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1b4e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
1b4f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
1b500 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 have.** not yet
1b510 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
1b520 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
1b530 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
1b540 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
1b550 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c part of.** a bl
1b560 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
1b570 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
1b580 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
1b590 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
1b5a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
1b5b0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f ealloc()]..*/.vo
1b5c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
1b5d0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 oc(int);.void *s
1b5e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
1b5f0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
1b600 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
1b610 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1b620 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
1b630 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
1b640 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 cs.**.** SQLite
1b650 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
1b660 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
1b670 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
1b680 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
1b690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
1b6a0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
1b6b0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
1b6c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1b6d0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
1b6e0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
1b6f0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
1b700 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
1b710 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b em..**.** ^The [
1b720 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1b730 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 sed()] routine r
1b740 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
1b750 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 r of bytes.** of
1b760 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c memory currentl
1b770 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d y outstanding (m
1b780 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 alloced but not
1b790 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 freed)..** ^The
1b7a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1b7b0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 highwater()] rou
1b7c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
1b7d0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 maximum.** valu
1b7e0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 e of [sqlite3_me
1b7f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e mory_used()] sin
1b800 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 ce the high-wate
1b810 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 r mark.** was la
1b820 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 st reset. ^The
1b830 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
1b840 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
1b850 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a ry_used()] and.*
1b860 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1b870 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
1b880 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 nclude any overh
1b890 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 ead.** added by
1b8a0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d SQLite in its im
1b8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1b8c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1b8d0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f )],.** but not o
1b8e0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 verhead added by
1b8f0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 the any underly
1b900 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 ing system libra
1b910 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 ry.** routines t
1b920 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c hat [sqlite3_mal
1b930 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e loc()] may call.
1b940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
1b950 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 ry high-water ma
1b960 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 rk is reset to t
1b970 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
1b980 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f of.** [sqlite3_
1b990 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 memory_used()] i
1b9a0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
1b9b0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a e parameter to.*
1b9c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1b9d0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
1b9e0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 s true. ^The va
1b9f0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
1ba00 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
1ba10 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d ry_highwater(1)]
1ba20 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 is the high-wat
1ba30 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 er mark.** prior
1ba40 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a to the reset..*
1ba50 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
1ba60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1ba70 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 sed(void);.sqlit
1ba80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
1ba90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1baa0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 r(int resetFlag)
1bab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1bac0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d F: Pseudo-Random
1bad0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f Number Generato
1bae0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 r.**.** SQLite c
1baf0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 ontains a high-q
1bb00 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 uality pseudo-ra
1bb10 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 ndom number gene
1bb20 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 rator (PRNG) use
1bb30 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 d to.** select r
1bb40 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 andom [ROWID | R
1bb50 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 OWIDs] when inse
1bb60 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 rting new record
1bb70 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 s into a table t
1bb80 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 hat.** already u
1bb90 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 ses the largest
1bba0 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d possible [ROWID]
1bbb0 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 . The PRNG is a
1bbc0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 lso used for.**
1bbd0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e the build-in ran
1bbe0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d dom() and random
1bbf0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 blob() SQL funct
1bc00 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 ions. This inte
1bc10 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 rface allows.**
1bc20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 applications to
1bc30 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 access the same
1bc40 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 PRNG for other p
1bc50 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e urposes..**.** ^
1bc60 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 A call to this r
1bc70 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 outine stores N
1bc80 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
1bc90 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ess into buffer
1bca0 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 P..**.** ^The fi
1bcb0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f rst time this ro
1bcc0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 utine is invoked
1bcd0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 (either interna
1bce0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 lly or by.** the
1bcf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 application) th
1bd00 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 e PRNG is seeded
1bd10 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 using randomnes
1bd20 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 s obtained.** fr
1bd30 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
1bd40 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ss method of the
1bd50 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
1bd60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
1bd70 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 * ^On all subseq
1bd80 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 uent invocations
1bd90 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e , the pseudo-ran
1bda0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
1bdb0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
1bdc0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
1bdd0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
1bde0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
1bdf0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
1be00 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 od..*/.void sqli
1be10 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
1be20 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
1be30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1be40 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
1be50 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
1be60 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 backs.**.** ^Thi
1be70 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
1be80 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ers an authorize
1be90 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
1bea0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
1beb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1bec0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
1bed0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
1bee0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 ument..** ^The a
1bef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1bf00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
1bf10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1bf20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
1bf30 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
1bf40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
1bf50 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
1bf60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1bf70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1bf80 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
1bf90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1bfa0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 re16_v2()]. ^At
1bfb0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e various.** poin
1bfc0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f ts during the co
1bfd0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 mpilation proces
1bfe0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 s, as logic is b
1bff0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 eing created.**
1c000 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
1c010 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 us actions, the
1c020 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1c030 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 ack is invoked t
1c040 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 o.** see if thos
1c050 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c e actions are al
1c060 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 lowed. ^The aut
1c070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1c080 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
1c090 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
1c0a0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
1c0b0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
1c0c0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
1c0d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
1c0e0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
1c0f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1c100 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
1c110 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
1c120 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
1c130 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
1c140 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
1c150 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
1c160 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
1c170 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 ror. ^If the au
1c180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1c190 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 k returns.** any
1c1a0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
1c1b0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
1c1c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
1c1d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
1c1e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 .** then the [sq
1c1f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1c200 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
1c210 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
1c220 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 gered.** the aut
1c230 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
1c240 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
1c250 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 message..**.** W
1c260 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1c270 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1c280 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 _OK], that means
1c290 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
1c2a0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f * requested is o
1c2b0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 k. ^When the ca
1c2c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
1c2d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
1c2e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
1c2f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
1c300 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
1c310 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
1c320 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1c330 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
1c340 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
1c350 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
1c360 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
1c370 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ied. .**.** ^The
1c380 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1c390 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
1c3a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
1c3b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 copy of the thi
1c3c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
1c3d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
1c3e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
1c3f0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 interface. ^The
1c400 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1c410 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1c420 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
1c430 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c r [SQLITE_COPY |
1c440 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
1c450 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
1c460 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
1c470 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
1c480 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 orized. ^The thi
1c490 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 rd through sixth
1c4a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
1c4b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
1c4c0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
1c4d0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
1c4e0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e contain addition
1c4f0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 al.** details ab
1c500 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 out the action t
1c510 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
1c520 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 .**.** ^If the a
1c530 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
1c540 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 QLITE_READ].** a
1c550 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
1c560 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1c570 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
1c580 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
1c590 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 atement] stateme
1c5a0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 nt is constructe
1c5b0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a d to substitute.
1c5c0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 ** a NULL value
1c5d0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
1c5e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
1c5f0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 t would have.**
1c600 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 been read if [SQ
1c610 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 LITE_OK] had bee
1c620 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 n returned. The
1c630 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1c640 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 .** return can b
1c650 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 e used to deny a
1c660 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 n untrusted user
1c670 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 access to indiv
1c680 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 idual.** columns
1c690 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 of a table..**
1c6a0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
1c6b0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 ode is [SQLITE_D
1c6c0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 ELETE] and the c
1c6d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
1c6e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ** [SQLITE_IGNOR
1c6f0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c E] then the [DEL
1c700 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 ETE] operation p
1c710 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a roceeds but the.
1c720 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 ** [truncate opt
1c730 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 imization] is di
1c740 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 sabled and all r
1c750 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
1c760 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a individually..**
1c770 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
1c780 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b r is used when [
1c790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
1c7a0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 | preparing].**
1c7b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 SQL statements f
1c7c0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 rom an untrusted
1c7d0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 source, to ensu
1c7e0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 re that the SQL
1c7f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f statements.** do
1c800 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 not try to acce
1c810 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 ss data they are
1c820 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 not allowed to
1c830 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 see, or that the
1c840 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 y do not.** try
1c850 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 to execute malic
1c860 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 ious statements
1c870 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 that damage the
1c880 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a database. For.*
1c890 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 * example, an ap
1c8a0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c plication may al
1c8b0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e low a user to en
1c8c0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a ter arbitrary.**
1c8d0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 SQL queries for
1c8e0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 evaluation by a
1c8f0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 database. But
1c900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1c910 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
1c920 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 the user to be
1c930 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 able to make arb
1c940 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 itrary changes t
1c950 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
1c960 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 e. An authorize
1c970 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 r could then be
1c980 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 put in place whi
1c990 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 le the.** user-e
1c9a0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 ntered SQL is be
1c9b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1c9c0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d pare | prepared]
1c9d0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f that.** disallo
1c9e0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 ws everything ex
1c9f0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 cept [SELECT] st
1ca00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1ca10 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
1ca20 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 t need to proces
1ca30 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 s SQL from untru
1ca40 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 sted sources.**
1ca50 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 might also consi
1ca60 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 der lowering res
1ca70 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 ource limits usi
1ca80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
1ca90 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 t()].** and limi
1caa0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 ting database si
1cab0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 ze using the [ma
1cac0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
1cad0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 RAGMA].** in add
1cae0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 ition to using a
1caf0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a n authorizer..**
1cb00 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e .** ^(Only a sin
1cb10 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 gle authorizer c
1cb20 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f an be in place o
1cb30 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e n a database con
1cb40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 nection.** at a
1cb50 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c time. Each call
1cb60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f to sqlite3_set_
1cb70 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 authorizer overr
1cb80 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 ides the.** prev
1cb90 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 ious call.)^ ^D
1cba0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
1cbb0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
1cbc0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
1cbd0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
1cbe0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
1cbf0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
1cc00 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
1cc10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
1cc20 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
1cc30 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
1cc40 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
1cc50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1cc60 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
1cc70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1cc80 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
1cc90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1cca0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
1ccb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
1ccc0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
1ccd0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1cce0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
1ccf0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
1cd00 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
1cd10 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 raph..**.** ^Whe
1cd20 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
1cd30 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 re_v2()] is used
1cd40 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 to prepare a st
1cd50 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 atement, the.**
1cd60 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 statement might
1cd70 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 be re-prepared d
1cd80 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
1cd90 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
1cda0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
1cdb0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
1cdc0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
1cdd0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
1cde0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
1cdf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1ce00 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
1ce10 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
1ce20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
1ce30 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 *.** ^Note that
1ce40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1ce50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1ce60 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a ed only during.*
1ce70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1ce80 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
1ce90 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a iants. Authoriz
1cea0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 ation is not.**
1ceb0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 performed during
1cec0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 statement evalu
1ced0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 ation in [sqlite
1cee0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 3_step()], unles
1cef0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 s.** as stated i
1cf00 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 n the previous p
1cf10 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 aragraph, sqlite
1cf20 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 3_step() invokes
1cf30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
1cf40 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 are_v2() to repr
1cf50 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
1cf60 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 t after a schema
1cf70 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 change..*/.int
1cf80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1cf90 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 orizer(. sqlite
1cfa0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 3*,. int (*xAut
1cfb0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e h)(void*,int,con
1cfc0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
1cfd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1cfe0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 ,const char*),.
1cff0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 void *pUserData
1d000 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1d010 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
1d020 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a Return Codes.**.
1d030 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
1d040 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1d050 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1d060 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d back function] m
1d070 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 ust.** return ei
1d080 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ther [SQLITE_OK]
1d090 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 or one of these
1d0a0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 two constants i
1d0b0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 n order.** to si
1d0c0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 gnal SQLite whet
1d0d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 her or not the a
1d0e0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
1d0f0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 ed. See the.**
1d100 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1d110 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1d120 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 izer documentati
1d130 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e on] for addition
1d140 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
1d150 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 n..**.** Note th
1d160 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 at SQLITE_IGNORE
1d170 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 is also used as
1d180 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 a [SQLITE_ROLLB
1d190 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 ACK | return cod
1d1a0 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b e].** from the [
1d1b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f sqlite3_vtab_on_
1d1c0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 conflict()] inte
1d1d0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e rface..*/.#defin
1d1e0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 e SQLITE_DENY
1d1f0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 1 /* Abort the
1d200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
1d210 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ith an error */.
1d220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1d230 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e GNORE 2 /* Don
1d240 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 't allow access,
1d250 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 but don't gener
1d260 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ate an error */.
1d270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1d280 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 Authorizer Acti
1d290 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 on Codes.**.** T
1d2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1d2b0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e authorizer()] in
1d2c0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
1d2d0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
1d2e0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 ction.** that is
1d2f0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 invoked to auth
1d300 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 orize certain SQ
1d310 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 L statement acti
1d320 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ons. The.** sec
1d330 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1d340 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
1d350 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
1d360 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
1d370 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 ** what action i
1d380 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a s being authoriz
1d390 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 ed. These are t
1d3a0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f he integer actio
1d3b0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 n codes that.**
1d3c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1d3d0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 allback may be p
1d3e0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 assed..**.** The
1d3f0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 se action code v
1d400 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 alues signify wh
1d410 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 at kind of opera
1d420 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a tion is to be.**
1d430 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
1d440 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 e 3rd and 4th pa
1d450 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 rameters to the
1d460 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a authorization.**
1d470 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1d480 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d on will be param
1d490 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 eters or NULL de
1d4a0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 pending on which
1d4b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 of these.** cod
1d4c0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 es is used as th
1d4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1d4e0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 er. ^(The 5th p
1d4f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
1d500 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ** authorizer ca
1d510 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 llback is the na
1d520 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
1d530 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d se ("main", "tem
1d540 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 p",.** etc.) if
1d550 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e applicable.)^ ^
1d560 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 The 6th paramete
1d570 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
1d580 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 zer callback.**
1d590 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
1d5a0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 he inner-most tr
1d5b0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 igger or view th
1d5c0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c at is responsibl
1d5d0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 e for.** the acc
1d5e0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e ess attempt or N
1d5f0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 ULL if this acce
1d600 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 ss attempt is di
1d610 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 rectly from.** t
1d620 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
1d630 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a e..*/./*********
1d640 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1d650 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1d660 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 3rd *********
1d670 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a *** 4th ********
1d680 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ***/.#define SQL
1d690 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
1d6a0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
1d6b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
1d6c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1d6d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1d6e0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
1d6f0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
1d700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1d710 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1d720 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1d730 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
1d740 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
1d750 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
1d760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1d770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1d780 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
1d790 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
1d7a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1d7b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1d7c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d7d0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
1d7e0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
1d7f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
1d800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1d810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1d820 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
1d830 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
1d840 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
1d850 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1d860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1d870 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
1d880 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
1d890 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
1d8a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1d8b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1d8c0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
1d8d0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
1d8e0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
1d8f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1d900 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
1d910 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
1d920 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
1d930 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1d940 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1d950 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1d960 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
1d970 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
1d980 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1d990 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1d9a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1d9b0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
1d9c0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
1d9d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1d9e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1d9f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1da00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
1da10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1da20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1da30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1da40 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1da50 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
1da60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1da70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1da80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1da90 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
1daa0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
1dab0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1dac0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1dad0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1dae0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
1daf0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
1db00 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1db10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1db20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1db30 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
1db40 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
1db50 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1db60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1db70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1db80 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
1db90 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
1dba0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1dbb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1dbc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1dbd0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
1dbe0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
1dbf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1dc00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1dc10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1dc20 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
1dc30 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
1dc40 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
1dc50 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
1dc60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1dc70 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
1dc80 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
1dc90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
1dca0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
1dcb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1dcc0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
1dcd0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
1dce0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
1dcf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1dd00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
1dd10 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
1dd20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 22 /* Oper
1dd30 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c ation NULL
1dd40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1dd50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
1dd60 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
1dd70 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
1dd80 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
1dd90 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
1dda0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
1ddb0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
1ddc0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
1ddd0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
1dde0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1ddf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
1de00 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
1de10 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
1de20 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
1de30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1de40 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
1de50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1de60 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
1de70 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1de80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1de90 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
1dea0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
1deb0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
1dec0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ded0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1dee0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
1def0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
1df00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1df10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1df20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1df30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
1df40 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 TABLE 29
1df50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1df60 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
1df70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1df80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 SQLITE_DROP_VTAB
1df90 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 LE 30
1dfa0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1dfb0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
1dfc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1dfd0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 QLITE_FUNCTION
1dfe0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 31
1dff0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
1e000 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 Function Name
1e010 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e020 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 LITE_SAVEPOINT
1e030 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 32 /
1e040 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
1e050 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 Savepoint Name
1e060 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e070 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 ITE_COPY
1e080 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
1e090 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 No longer used
1e0a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1e0b0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
1e0c0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
1e0d0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1e0e0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
1e0f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
1e100 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
1e110 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
1e120 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
1e130 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
1e140 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
1e150 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ts..**.** ^The c
1e160 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1e170 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
1e180 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
1e190 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
1e1a0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
1e1b0 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
1e1c0 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
1e1d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
1e1e0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 p()]..** ^The sq
1e1f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
1e200 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1e210 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 d with a UTF-8 r
1e220 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a endering of the.
1e230 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1e240 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 text as the sta
1e250 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
1e260 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a ins executing..*
1e270 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 * ^(Additional s
1e280 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
1e290 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f allbacks might o
1e2a0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
1e2b0 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
1e2c0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
1e2d0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
1e2e0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
1e2f0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
1e300 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
1e310 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
1e320 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a trigger.)^.**.**
1e330 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
1e340 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
1e350 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
1e360 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
1e370 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
1e380 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
1e390 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
1e3a0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
1e3b0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
1e3c0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
1e3d0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
1e3e0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
1e3f0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
1e400 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
1e410 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
1e420 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
1e430 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
1e440 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
1e450 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
1e460 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
1e470 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
1e480 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
1e490 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
1e4a0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
1e4b0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
1e4c0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
1e4d0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
1e4e0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
1e4f0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
1e500 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
1e510 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
1e520 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
1e530 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
1e540 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
1e550 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
1e560 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
1e570 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
1e580 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
1e590 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
1e5a0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
1e5b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1e5c0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 e..*/.void *sqli
1e5d0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 te3_trace(sqlite
1e5e0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 3*, void(*xTrace
1e5f0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
1e600 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 ar*), void*);.SQ
1e610 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
1e620 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f L void *sqlite3_
1e630 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a profile(sqlite3*
1e640 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 ,. void(*xProf
1e650 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ile)(void*,const
1e660 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 char*,sqlite3_u
1e670 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a int64), void*);.
1e680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1e690 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
1e6a0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
1e6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f ^The sqlite3_pro
1e6c0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c gress_handler(D,
1e6d0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 N,X,P) interface
1e6e0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
1e6f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
1e700 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 X to be invoked
1e710 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
1e720 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
1e730 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 g calls to.** [s
1e740 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
1e750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 and [sqlite3_ge
1e770 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a t_table()] for.*
1e780 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1e790 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 ction D. An exa
1e7a0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 mple use for thi
1e7b0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 s.** interface i
1e7c0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
1e7d0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
1e7e0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
1e7f0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 .** ^The paramet
1e800 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 er P is passed t
1e810 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e hrough as the on
1e820 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ly parameter to
1e830 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the .** callback
1e840 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 function X. ^T
1e850 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 he parameter N i
1e860 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1e870 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 .** [virtual mac
1e880 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e hine instruction
1e890 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c s] that are eval
1e8a0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 uated between su
1e8b0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f ccessive.** invo
1e8c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 cations of the c
1e8d0 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a allback X..**.**
1e8e0 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^Only a single
1e8f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1e900 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 may be defined
1e910 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a at one time per.
1e920 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1e930 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e nection]; settin
1e940 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 g a new progress
1e950 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 handler cancels
1e960 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e the.** old one.
1e970 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d ^Setting param
1e980 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 eter X to NULL d
1e990 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 isables the prog
1e9a0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
1e9b0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 ^The progress h
1e9c0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 andler is also d
1e9d0 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 isabled by setti
1e9e0 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 ng N to a value
1e9f0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a less.** than 1..
1ea00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 **.** ^If the pr
1ea10 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
1ea20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
1ea30 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 , the operation
1ea40 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 is.** interrupte
1ea50 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 d. This feature
1ea60 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1ea70 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 implement a.** "
1ea80 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f Cancel" button o
1ea90 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 n a GUI progress
1eaa0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a dialog box..**.
1eab0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 ** The progress
1eac0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1ead0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
1eae0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
1eaf0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
1eb00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1eb10 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
1eb20 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1eb30 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ler..** Note tha
1eb40 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
1eb50 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
1eb60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
1eb70 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
1eb80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1eb90 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
1eba0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
1ebb0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
1ebc0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 graph..**.*/.voi
1ebd0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
1ebe0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
1ebf0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
1ec00 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
1ec10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ec20 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
1ec30 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
1ec40 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ion.**.** ^These
1ec50 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
1ec60 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
1ec70 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 e file as specif
1ec80 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
1ec90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1eca0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 . ^The filename
1ecb0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
1ecc0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
1ecd0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
1ece0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1ecf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 e3_open_v2() and
1ed00 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
1ed10 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a e native byte.**
1ed20 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
1ed30 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 e3_open16(). ^(A
1ed40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1ed50 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
1ed60 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
1ed70 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
1ed80 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
1ed90 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
1eda0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
1edb0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
1edc0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
1edd0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
1ede0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
1edf0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
1ee00 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
1ee10 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
1ee20 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
1ee30 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
1ee40 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
1ee50 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 .)^ ^(If the dat
1ee60 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1ee70 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
1ee80 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
1ee90 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
1eea0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
1eeb0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
1eec0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
1eed0 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a turned.)^ ^The.*
1eee0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1eef0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
1ef00 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
1ef10 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
1ef20 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
1ef30 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
1ef40 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
1ef50 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c f the error foll
1ef60 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 owing a failure
1ef70 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
1ef80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1ef90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
1efa0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
1efb0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 oding for the da
1efc0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 tabase will be U
1efd0 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 TF-8 if.** sqlit
1efe0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
1eff0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
1f000 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
1f010 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
1f020 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
1f030 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 if sqlite3_open1
1f040 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 6() is used..**.
1f050 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
1f060 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
1f070 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
1f080 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
1f090 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
1f0a0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
1f0b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
1f0c0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
1f0d0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
1f0e0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
1f0f0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
1f100 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
1f110 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
1f120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
1f130 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
1f140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
1f150 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
1f160 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
1f170 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
1f180 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
1f190 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
1f1a0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
1f1b0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
1f1c0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
1f1d0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
1f1e0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
1f1f0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
1f200 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
1f210 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
1f220 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
1f230 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
1f240 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
1f250 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
1f260 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
1f270 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
1f280 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
1f290 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
1f2a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
1f2b0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
1f2c0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
1f2d0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
1f2e0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
1f2f0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
1f300 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1f310 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1f320 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
1f330 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
1f340 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
1f350 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
1f360 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
1f370 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
1f380 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
1f390 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1f3a0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
1f3b0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1f3c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
1f3d0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
1f3e0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
1f3f0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
1f400 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
1f410 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
1f420 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1f430 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
1f440 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
1f450 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
1f460 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
1f470 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
1f480 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
1f490 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
1f4a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1f4b0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
1f4c0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
1f4d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1f4e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1f4f0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1f500 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
1f510 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
1f520 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
1f530 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
1f540 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
1f550 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
1f560 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
1f570 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
1f580 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
1f590 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
1f5a0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
1f5b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1f5c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1f5d0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
1f5e0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
1f5f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
1f600 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
1f610 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
1f620 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1f630 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
1f640 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
1f650 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
1f660 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
1f670 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
1f680 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
1f690 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
1f6a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1f6b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
1f6c0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
1f6d0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
1f6e0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
1f6f0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
1f700 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
1f710 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
1f720 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
1f730 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
1f740 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
1f750 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
1f760 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
1f770 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1f780 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
1f790 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
1f7a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
1f7b0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
1f7c0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
1f7d0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
1f7e0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
1f7f0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
1f800 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
1f810 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
1f820 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
1f830 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
1f840 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
1f850 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
1f860 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
1f870 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
1f880 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
1f890 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
1f8a0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
1f8b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1f8c0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
1f8d0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
1f8e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
1f8f0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
1f900 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
1f910 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f920 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
1f930 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
1f940 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
1f950 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
1f960 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
1f970 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
1f980 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
1f990 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
1f9a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
1f9b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1f9c0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
1f9d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
1f9e0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
1f9f0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
1fa00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1fa10 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
1fa20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
1fa30 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
1fa40 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1fa50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
1fa60 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
1fa70 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
1fa80 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
1fa90 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
1faa0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
1fab0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
1fac0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
1fad0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
1fae0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
1faf0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
1fb00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
1fb10 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
1fb20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1fb30 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
1fb40 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
1fb50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
1fb60 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
1fb70 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
1fb80 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
1fb90 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
1fba0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
1fbb0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
1fbc0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
1fbd0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
1fbe0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
1fbf0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
1fc00 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
1fc10 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
1fc20 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
1fc30 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
1fc40 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
1fc50 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
1fc60 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
1fc70 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
1fc80 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
1fc90 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
1fca0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
1fcb0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
1fcc0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
1fcd0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
1fce0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
1fcf0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
1fd00 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
1fd10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1fd20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
1fd30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
1fd40 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
1fd50 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
1fd60 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
1fd70 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
1fd80 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
1fd90 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
1fda0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
1fdb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1fdc0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
1fdd0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
1fde0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
1fdf0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
1fe00 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
1fe10 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
1fe20 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
1fe30 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1fe40 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
1fe50 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
1fe60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
1fe70 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
1fe80 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
1fe90 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
1fea0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
1feb0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
1fec0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
1fed0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
1fee0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
1fef0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
1ff00 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
1ff10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1ff20 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 ption..** As of
1ff30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1ff40 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 .7.7, URI filena
1ff50 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
1ff60 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
1ff70 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
1ff80 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
1ff90 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
1ffa0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
1ffb0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
1ffc0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
1ffd0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
1ffe0 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
1fff0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
20000 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
20010 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
20020 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
20030 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
20040 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
20050 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
20060 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
20070 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
20080 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
20090 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
200a0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
200b0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
200c0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
200d0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
200e0 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
200f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
20100 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
20110 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
20120 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
20130 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
20140 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
20150 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
20160 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
20170 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
20180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
20190 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
201a0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
201b0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
201c0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
201d0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
201e0 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
201f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
20200 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
20210 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
20220 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
20230 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
20240 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
20250 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
20260 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
20270 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
20280 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
20290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
202a0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
202b0 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c .** ^On windows,
202c0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
202d0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
202e0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
202f0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
20300 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
20310 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 )..**.** [[core
20320 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 URI query parame
20330 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 ters]].** The qu
20340 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
20350 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 a URI may conta
20360 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 in parameters th
20370 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 at are interpret
20380 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 ed.** either by
20390 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f SQLite itself, o
203a0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 r by a [VFS | cu
203b0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 stom VFS impleme
203c0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c ntation]..** SQL
203d0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 ite interprets t
203e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
203f0 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 ee query paramet
20400 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ers:.**.** <ul>.
20410 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 ** <li> <b>vfs
20420 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 </b>: ^The "vfs"
20430 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
20440 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 e used to specif
20450 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a y the name of.**
20460 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 a VFS objec
20470 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 t that provides
20480 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
20490 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
204a0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 hat should.**
204b0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 be used to acc
204c0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
204d0 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e file on disk. ^
204e0 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 If this option i
204f0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 s set to.**
20500 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
20510 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
20520 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 object is used.
20530 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
20540 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 nknown.** VF
20550 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e S is an error. ^
20560 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
20570 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
20580 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 the vfs option
20590 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e is.** presen
205a0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 t, then the VFS
205b0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
205c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 option takes pr
205d0 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a ecedence over.**
205e0 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 the value p
205f0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 assed as the fou
20600 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
20610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
20620 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
20630 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 <b>mode</b>: ^(
20640 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 The mode paramet
20650 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
20660 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 either "ro", "r
20670 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 w",.** "rwc"
20680 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 , or "memory". A
20690 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 ttempting to set
206a0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 it to any other
206b0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 value is.**
206c0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a an error)^. .**
206d0 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 ^If "ro" is
206e0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e specified, then
206f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
20700 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
20710 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 -only .** ac
20720 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 cess, just as if
20730 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
20740 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 N_READONLY] flag
20750 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e had been set in
20760 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 the .** thi
20770 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
20780 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
20790 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f . ^If the mode o
207a0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 ption is set to
207b0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 .** "rw", th
207c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
207d0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
207e0 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f ad-write (but no
207f0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 t create) .**
20800 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 access, as if
20810 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
20820 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 WRITE (but not S
20830 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
20840 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 E) had .** b
20850 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 een set. ^Value
20860 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c "rwc" is equival
20870 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 ent to setting b
20880 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 oth .** SQLI
20890 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
208a0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 E and SQLITE_OPE
208b0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 N_CREATE. ^If t
208c0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
208d0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 s.** set to
208e0 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 "memory" then a
208f0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 pure [in-memory
20900 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e database] that n
20910 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 ever reads.**
20920 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d or writes from
20930 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e disk is used. ^
20940 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 It is an error t
20950 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 o specify a valu
20960 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 e for.** the
20970 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
20980 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 that is less res
20990 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 trictive than th
209a0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a at specified by.
209b0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 ** the flags
209c0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 passed in the t
209d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
209e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
209f0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
20a00 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 > <b>cache</b>:
20a10 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d ^The cache param
20a20 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
20a30 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 to either "share
20a40 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 d" or.** "pr
20a50 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 ivate". ^Setting
20a60 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 it to "shared"
20a70 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
20a80 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 setting the.**
20a90 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
20aa0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 SHAREDCACHE bit
20ab0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 in the flags arg
20ac0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
20ad0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f ** sqlite3_o
20ae0 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 pen_v2(). ^Setti
20af0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 ng the cache par
20b00 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 ameter to "priva
20b10 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 te" is .** e
20b20 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
20b30 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f ting the SQLITE_
20b40 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
20b50 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 E bit..** ^I
20b60 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
20b70 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
20b80 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 the "cache" para
20b90 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 meter is present
20ba0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 in.** a URI
20bb0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 filename, its v
20bc0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 alue overrides a
20bd0 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 ny behaviour req
20be0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e uested by settin
20bf0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f g.** SQLITE_
20c00 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
20c10 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e E or SQLITE_OPEN
20c20 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 _SHAREDCACHE fla
20c30 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a g..** </ul>.**.*
20c40 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
20c50 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
20c60 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
20c70 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
20c80 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
20c90 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
20ca0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
20cb0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
20cc0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
20cd0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
20ce0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
20cf0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
20d00 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
20d10 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
20d20 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
20d30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
20d40 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
20d50 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
20d60 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
20d70 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
20d80 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
20d90 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
20da0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
20db0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
20dc0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
20dd0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
20de0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
20df0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
20e00 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
20e10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
20e20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
20e30 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
20e40 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
20e50 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
20e60 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
20e70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
20e80 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
20e90 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
20ea0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
20eb0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
20ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
20ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
20ee0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
20ef0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
20f00 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
20f10 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
20f20 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
20f30 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
20f40 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
20f50 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
20f60 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
20f70 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
20f80 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
20f90 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
20fa0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
20fb0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
20fc0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
20fd0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
20fe0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
20ff0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
21000 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
21010 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
21020 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
21030 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
21040 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
21050 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
21060 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
21070 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
21080 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
21090 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
210a0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
210b0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
210c0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
210d0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
210e0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
210f0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
21100 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
21110 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
21120 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
21130 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
21140 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
21150 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
21160 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
21170 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
21180 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
21190 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
211a0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
211b0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
211c0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
211d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
211e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
211f0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 =unix-nolock <td
21200 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 >.** Op
21210 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 en file "/home/f
21220 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 red/data.db". Us
21230 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 e the special VF
21240 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e S "unix-nolock".
21250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
21260 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
21270 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a eadonly <td> .**
21280 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
21290 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 or. "readonly" i
212a0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 s not a valid op
212b0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f tion for the "mo
212c0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a de" parameter..*
212d0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
212e0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 ^URI hexadecima
212f0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
21300 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 es (%HH) are sup
21310 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 ported within th
21320 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 e path and.** qu
21330 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
21340 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 f a URI. A hexad
21350 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
21360 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 quence consists
21370 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 of a.** percent
21380 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c sign - "%" - fol
21390 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 lowed by exactly
213a0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c two hexadecimal
213b0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 digits .** spec
213c0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 ifying an octet
213d0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 value. ^Before t
213e0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 he path or query
213f0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
21400 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
21410 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
21420 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 , they are encod
21430 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 ed using UTF-8 a
21440 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 nd all .** hexad
21450 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
21460 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 quences replaced
21470 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 by a single byt
21480 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
21490 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e .** correspondin
214a0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 g octet. If this
214b0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 process generat
214c0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 es an invalid UT
214d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a F-8 encoding,.**
214e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
214f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
21500 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
21510 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
21520 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
21530 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
21540 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
21550 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
21560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
21570 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
21580 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
21590 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
215a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
215b0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
215c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
215d0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
215e0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
215f0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
21600 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
21610 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
21620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
21630 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
21640 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e v2()..**.** <b>N
21650 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 ote to Windows R
21660 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 untime users:</b
21670 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 > The temporary
21680 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 directory must
21690 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 be set.** prior
216a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 to calling sqlit
216b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
216c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
216d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 Otherwise, vari
216e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 ous.** features
216f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 that require the
21700 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 use of temporar
21710 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c y files may fail
21720 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
21730 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f : [sqlite3_temp_
21740 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e directory].*/.in
21750 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
21760 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
21770 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
21780 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
21790 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
217a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
217b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
217c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
217d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
217e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
217f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
21800 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
21810 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
21820 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
21830 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
21840 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
21850 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
21860 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
21870 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
21880 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
21890 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
218a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
218b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
218c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
218d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
218e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
218f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
21900 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
21910 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
21920 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
21930 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
21940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
21950 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
21960 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
21970 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
21980 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
21990 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
219a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
219b0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
219c0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
219d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
219e0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
219f0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
21a00 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
21a10 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
21a20 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
21a30 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
21a40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
21a50 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
21a60 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
21a70 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
21a80 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
21a90 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
21aa0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
21ab0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
21ac0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
21ad0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
21ae0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
21af0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
21b00 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
21b10 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
21b20 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
21b30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
21b40 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
21b50 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
21b60 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
21b70 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
21b80 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
21b90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
21ba0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
21bb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
21bc0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
21bd0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
21be0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
21bf0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
21c00 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
21c10 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
21c20 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
21c30 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
21c40 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
21c50 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
21c60 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
21c70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
21c80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
21c90 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
21ca0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
21cb0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
21cc0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
21cd0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
21ce0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
21cf0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
21d00 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
21d10 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
21d20 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
21d30 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
21d40 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
21d50 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
21d60 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
21d70 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
21d80 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
21d90 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
21da0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
21db0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
21dc0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
21dd0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
21de0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
21df0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
21e00 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
21e10 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
21e20 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
21e30 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
21e40 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
21e50 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
21e60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
21e70 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
21e80 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
21e90 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
21ea0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
21eb0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
21ec0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
21ed0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
21ee0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
21ef0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
21f00 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
21f10 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
21f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
21f30 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
21f40 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
21f50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
21f60 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
21f70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
21f80 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
21f90 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
21fa0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
21fb0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
21fc0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
21fd0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
21fe0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
21ff0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
22000 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
22010 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
22020 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
22030 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
22040 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
22050 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
22060 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
22070 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
22080 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
22090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
220a0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
220b0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
220c0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
220d0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
220e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
220f0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
22100 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
22110 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
22120 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
22130 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
22140 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 sirable..*/.cons
22150 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
22160 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
22170 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
22180 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
22190 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 *zParam);.int sq
221a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
221b0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
221c0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
221d0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
221e0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f fault);.sqlite3_
221f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 int64 sqlite3_ur
22200 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
22210 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
22220 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
22230 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
22240 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
22250 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
22260 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
22270 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
22280 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
22290 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
222a0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
222b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
222c0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
222d0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
222e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
222f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
22300 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
22310 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
22320 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
22330 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
22340 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
22350 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
22360 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
22370 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
22380 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
22390 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
223a0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
223b0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
223c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
223d0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
223e0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
223f0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
22400 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
22410 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
22420 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
22430 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
22440 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
22450 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
22460 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
22470 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
22480 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
22490 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
224a0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
224b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
224c0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
224d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
224e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
224f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
22500 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
22510 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
22520 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
22530 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
22540 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
22550 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
22560 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
22570 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
22580 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
22590 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
225a0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
225b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
225c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
225d0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
225e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
225f0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 e3_errstr() inte
22600 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
22610 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 e English-langua
22620 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 ge text.** that
22630 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 describes the [r
22640 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 esult code], as
22650 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f UTF-8..** ^(Memo
22660 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
22670 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
22680 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
22690 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 nternally.** and
226a0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 must not be fre
226b0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
226c0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 ation)^..**.** W
226d0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
226e0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
226f0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
22700 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
22710 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
22720 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
22730 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
22740 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
22750 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
22760 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
22770 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
22780 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
22790 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
227a0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
227b0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
227c0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
227d0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
227e0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
227f0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
22800 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
22810 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
22820 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
22830 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
22840 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
22850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
22860 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
22870 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
22880 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
22890 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
228a0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
228b0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
228c0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
228d0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
228e0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
228f0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
22900 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
22910 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
22920 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
22930 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
22940 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
22950 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
22960 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
22970 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
22980 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
22990 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
229a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
229b0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
229c0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
229d0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
229e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
229f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
22a00 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
22a10 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *db);.int sqlite
22a20 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
22a30 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
22a40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
22a50 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
22a60 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 te3*);.const voi
22a70 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
22a80 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 g16(sqlite3*);.c
22a90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
22aa0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a e3_errstr(int);.
22ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22ac0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
22ad0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
22ae0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
22af0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
22b00 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
22b10 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
22b20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
22b30 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
22b40 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
22b50 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
22b60 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
22b70 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
22b80 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
22b90 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
22ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
22bb0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
22bc0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
22bd0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
22be0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
22bf0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
22c00 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
22c10 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
22c20 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
22c30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
22c40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
22c50 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
22c60 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
22c70 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
22c80 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
22c90 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
22ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
22cb0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
22cc0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
22cd0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
22ce0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
22cf0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
22d00 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
22d10 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
22d20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
22d30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
22d40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
22d50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
22d60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
22d70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
22d80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
22d90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
22da0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
22db0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
22dc0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
22dd0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
22de0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
22df0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
22e00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
22e10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
22e20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
22e30 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
22e40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
22e50 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
22e60 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
22e70 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
22e80 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
22e90 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
22ea0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
22eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
22ec0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
22ed0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
22ee0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
22ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22f00 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
22f10 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
22f20 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
22f30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
22f40 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
22f50 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
22f60 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
22f70 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
22f80 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
22f90 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
22fa0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
22fb0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
22fc0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
22fd0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
22fe0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
22ff0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
23000 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
23010 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
23020 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
23030 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
23040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
23050 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
23060 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
23070 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
23080 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
23090 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
230a0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
230b0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
230c0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
230d0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
230e0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
230f0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
23100 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
23110 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
23120 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
23130 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
23140 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
23150 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
23160 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
23170 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
23180 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
23190 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
231a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
231b0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
231c0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
231d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
231e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
231f0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
23200 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
23210 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
23220 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
23230 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
23240 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
23250 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
23260 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
23270 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
23280 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
23290 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
232a0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
232b0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
232c0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
232d0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
232e0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
232f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
23300 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
23310 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
23320 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
23330 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
23340 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
23350 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
23360 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
23370 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
23380 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
23390 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
233a0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
233b0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
233c0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
233d0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
233e0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
233f0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
23400 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
23410 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
23420 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
23430 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
23440 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
23450 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
23460 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
23470 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
23480 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
23490 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
234a0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
234b0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
234c0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
234d0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
234e0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
234f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
23500 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
23510 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
23520 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
23530 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
23540 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
23550 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
23560 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
23570 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
23580 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
23590 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
235a0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
235b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
235c0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
235d0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
235e0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
235f0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
23600 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
23610 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
23620 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
23630 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
23640 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
23650 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
23660 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
23670 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
23680 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
23690 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
236a0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
236b0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
236c0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
236d0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
236e0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
236f0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
23700 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
23710 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
23720 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
23730 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
23740 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
23750 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
23760 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
23770 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
23780 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
23790 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
237a0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
237b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
237c0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
237d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
237e0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
237f0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
23800 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
23810 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
23820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
23830 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
23840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
23850 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
23860 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
23870 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
23880 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
23890 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
238a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
238b0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
238c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
238d0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
238e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
238f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
23900 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
23910 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
23920 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
23930 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
23940 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
23950 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
23960 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
23970 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
23980 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
23990 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
239a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
239b0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
239c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
239d0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
239e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
239f0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
23a00 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
23a10 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
23a20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
23a30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
23a40 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
23a50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
23a60 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
23a70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
23a80 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
23a90 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
23aa0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
23ab0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
23ac0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
23ad0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
23ae0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
23af0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
23b00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
23b10 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
23b20 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
23b30 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
23b40 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
23b50 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
23b60 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
23b70 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
23b80 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
23b90 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
23ba0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
23bb0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
23bc0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
23bd0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
23be0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
23bf0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
23c00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
23c10 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
23c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
23c30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
23c40 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
23c50 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
23c60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
23c70 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
23c80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
23c90 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
23ca0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
23cb0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
23cc0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
23cd0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
23ce0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
23cf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
23d00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
23d10 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
23d20 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
23d30 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
23d40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
23d50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
23d60 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
23d70 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
23d80 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
23d90 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
23da0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
23db0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
23dc0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
23dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
23de0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
23df0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
23e00 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
23e10 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
23e20 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
23e30 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
23e40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
23e50 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
23e60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
23e70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
23e80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
23e90 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
23ea0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
23eb0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
23ec0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
23ed0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
23ee0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
23ef0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
23f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
23f10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
23f20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
23f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
23f40 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
23f50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
23f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
23f70 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
23f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
23fa0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
23fb0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
23fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23fd0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
23fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23ff0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
24000 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
24010 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
24020 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
24030 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
24040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24050 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
24060 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
24070 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
24080 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
24090 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
240a0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
240b0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
240c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
240d0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
240e0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 10../*.** CA
240f0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
24100 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
24110 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 nt.** KEYWORDS:
24120 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 {SQL statement c
24130 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 ompiler}.**.** T
24140 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
24150 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
24160 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
24170 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
24180 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
24190 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
241a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
241b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
241c0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
241d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
241e0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
241f0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
24200 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
24210 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
24220 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
24230 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
24240 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
24250 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
24260 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
24270 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
24280 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
24290 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
242a0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
242b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
242c0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
242d0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
242e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
242f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
24300 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
24310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
24320 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
24330 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
24340 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
24350 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
24360 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
24370 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
24380 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
24390 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 rgument is less
243a0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
243b0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
243c0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
243d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
243e0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f ^If nByte is no
243f0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
24400 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
24410 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
24420 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
24430 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 zSql. ^When nB
24440 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
24450 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
24460 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
24470 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
24480 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
24490 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
244a0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
244b0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
244c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
244d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
244e0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
244f0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
24500 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
24510 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
24520 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
24530 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
24540 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
24550 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
24560 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
24570 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
24580 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
24590 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
245a0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
245b0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
245c0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
245d0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 tes as this save
245e0 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 s SQLite from ha
245f0 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 ving to.** make
24600 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e a copy of the in
24610 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a put string..**.*
24620 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
24630 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
24640 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
24650 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
24660 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
24670 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
24680 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
24690 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
246a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
246b0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
246c0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
246d0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
246e0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
246f0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
24700 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
24710 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
24720 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
24730 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
24740 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
24750 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
24760 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
24770 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
24780 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
24790 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
247a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
247b0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
247c0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
247d0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
247e0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
247f0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
24800 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
24810 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
24820 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
24830 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
24840 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
24850 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
24860 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
24870 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
24880 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
24890 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
248a0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
248b0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
248c0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
248d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
248e0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
248f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
24900 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
24910 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
24920 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
24930 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
24940 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
24950 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
24960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
24970 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
24980 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
24990 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
249a0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
249b0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
249c0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
249d0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
249e0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
249f0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
24a00 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
24a10 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
24a20 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
24a30 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
24a40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
24a50 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
24a60 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
24a70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
24a80 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
24a90 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
24aa0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
24ab0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
24ac0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
24ad0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
24ae0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
24af0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
24b00 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
24b10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
24b20 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
24b30 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
24b40 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
24b50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
24b60 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
24b70 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
24b80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
24b90 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
24ba0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
24bb0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
24bc0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
24bd0 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 t again..** </li
24be0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
24bf0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
24c00 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
24c10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
24c20 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
24c30 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
24c40 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
24c50 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
24c60 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
24c70 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
24c80 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
24c90 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
24ca0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
24cb0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
24cc0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
24cd0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
24ce0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
24cf0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
24d00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
24d10 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
24d20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
24d30 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
24d40 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
24d50 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
24d60 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
24d70 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
24d80 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
24d90 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
24da0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
24db0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
24dc0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
24dd0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
24de0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
24df0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
24e00 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
24e10 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
24e20 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
24e30 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
24e40 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
24e50 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
24e60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
24e70 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
24e80 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
24e90 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
24ea0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
24eb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
24ec0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
24ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
24ee0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
24ef0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
24f00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24f10 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
24f20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
24f30 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
24f40 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
24f50 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
24f60 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
24f70 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
24f80 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
24f90 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
24fa0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
24fb0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
24fc0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
24fd0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
24fe0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
24ff0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
25000 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
25010 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
25020 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
25030 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
25040 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
25050 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 led..** the .**
25060 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
25070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 /.int sqlite3_pr
25080 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
25090 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
250a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
250b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
250c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
250d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
250e0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
250f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
25100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
25110 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
25120 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
25130 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
25140 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
25150 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
25160 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
25170 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
25180 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
25190 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
251a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
251b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
251c0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
251d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
251e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
251f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
25200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
25210 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
25220 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
25230 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
25240 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
25250 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
25260 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
25270 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
25280 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
25290 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
252a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
252b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
252c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
252d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
252e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
252f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
25300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
25310 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
25320 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
25330 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
25340 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
25350 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
25360 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
25370 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
25380 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
25390 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
253a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
253b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
253c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
253d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
253e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
253f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
25400 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
25410 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
25420 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
25430 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
25440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
25450 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
25460 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
25470 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
25480 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
25490 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
254a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
254b0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
254c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
254d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
254e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
254f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
25500 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
25510 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
25520 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
25530 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
25540 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
25550 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
25560 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
25570 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
25580 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a Sql */.);../*.**
25590 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
255a0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
255b0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 SQL.**.** ^This
255c0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
255d0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
255e0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
255f0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
25600 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
25610 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
25620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
25630 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
25640 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
25650 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
25660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
25670 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
25680 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
25690 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
256a0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
256b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
256c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
256d0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
256e0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
256f0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
25700 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 atabase.**.** ^T
25710 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
25720 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 readonly(X) inte
25730 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
25740 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
25750 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 .** and only if
25760 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25770 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 atement] X makes
25780 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 no direct chang
25790 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e es to.** the con
257a0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 tent of the data
257b0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a base file..**.**
257c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c Note that [appl
257d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
257e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f SQL functions] o
257f0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 r.** [virtual ta
25800 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e bles] might chan
25810 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
25820 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 indirectly as a
25830 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a side effect. .*
25840 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
25850 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
25860 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e on defines a fun
25870 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 ction "eval()" t
25880 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 hat .** calls [s
25890 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
258a0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 then the followi
258b0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
258c0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 would.** change
258d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
258e0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d le through side-
258f0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c effects:.**.** <
25900 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
25910 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 .** SELECT ev
25920 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 al('DELETE FROM
25930 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a t1') FROM t2;.**
25940 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
25950 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 ote>.**.** But b
25960 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 ecause the [SELE
25970 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f CT] statement do
25980 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
25990 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a e database file.
259a0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c ** directly, sql
259b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
259c0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c ly() would still
259d0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a return true.)^.
259e0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 **.** ^Transacti
259f0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 on control state
25a00 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 ments such as [B
25a10 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c EGIN], [COMMIT],
25a20 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 [ROLLBACK],.**
25a30 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 [SAVEPOINT], and
25a40 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 [RELEASE] cause
25a50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
25a60 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
25a70 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 rn true,.** sinc
25a80 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 e the statements
25a90 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e themselves do n
25aa0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 ot actually modi
25ab0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
25ac0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 but.** rather th
25ad0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 ey control the t
25ae0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 iming of when ot
25af0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d her statements m
25b00 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 odify the .** da
25b10 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 tabase. ^The [A
25b20 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 TTACH] and [DETA
25b30 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 CH] statements a
25b40 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c lso cause.** sql
25b50 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
25b60 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
25b70 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 rue since, while
25b80 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 those statement
25b90 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 s.** change the
25ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 configuration of
25bb0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
25bc0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 ection, they do
25bd0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 not make .** cha
25be0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 nges to the cont
25bf0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
25c00 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 ase files on dis
25c10 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 k..*/.int sqlite
25c20 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
25c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
25c40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
25c50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
25c60 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 If A Prepared S
25c70 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 tatement Has Bee
25c80 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 n Reset.**.** ^T
25c90 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
25ca0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
25cb0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
25cc0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
25cd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
25ce0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
25cf0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
25d00 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
25d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
25d20 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f p(S)] but has no
25d30 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 t run to complet
25d40 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e ion and/or has n
25d50 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 ot .** been rese
25d60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
25d70 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 _reset(S)]. ^Th
25d80 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
25d90 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 usy(S).** interf
25da0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 ace returns fals
25db0 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c e if S is a NULL
25dc0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 pointer. If S
25dd0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c is not a .** NUL
25de0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 L pointer and is
25df0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 not a pointer t
25e00 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 o a valid [prepa
25e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
25e20 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 * object, then t
25e30 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
25e40 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
25e50 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
25e60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
25e70 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
25e80 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 sed in combinati
25e90 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 on [sqlite3_next
25ea0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c _stmt()].** to l
25eb0 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 ocate all prepar
25ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 ed statements as
25ed0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
25ee0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e database .** con
25ef0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 nection that are
25f00 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e in need of bein
25f10 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 g reset. This c
25f20 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 an be used,.** f
25f30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 or example, in d
25f40 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e iagnostic routin
25f50 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 es to search for
25f60 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 prepared .** st
25f70 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 atements that ar
25f80 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e e holding a tran
25f90 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f saction open..*/
25fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d .int sqlite3_stm
25fb0 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 t_busy(sqlite3_s
25fc0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
25fd0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 PI3REF: Dynamica
25fe0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 lly Typed Value
25ff0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
26000 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
26010 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
26020 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
26030 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
26040 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
26050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
26060 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
26070 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
26080 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
26090 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
260a0 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
260b0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
260c0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
260d0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
260e0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 ^Values stored
260f0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 in sqlite3_value
26100 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 objects.** can
26110 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f be integers, flo
26120 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
26130 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f es, strings, BLO
26140 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a Bs, or NULL..**.
26150 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 ** An sqlite3_va
26160 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 lue object may b
26170 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 e either "protec
26180 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 ted" or "unprote
26190 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 cted"..** Some i
261a0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
261b0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 e a protected sq
261c0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 lite3_value. Ot
261d0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
261e0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 * will accept ei
261f0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 ther a protected
26200 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 or an unprotect
26210 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
26220 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 ..** Every inter
26230 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 face that accept
26240 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 s sqlite3_value
26250 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 arguments specif
26260 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f ies.** whether o
26270 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 r not it require
26280 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 s a protected sq
26290 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
262a0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
262b0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
262c0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
262d0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
262e0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
262f0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
26300 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
26310 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
26320 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
26330 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
26340 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
26350 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
26360 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
26370 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
26380 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
26390 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
263a0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
263b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
263c0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
263d0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
263e0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
263f0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
26400 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
26410 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
26420 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
26430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
26440 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
26450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
26460 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
26470 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
26480 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
26490 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
264a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
264b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
264c0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
264d0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
264e0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
264f0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
26500 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
26510 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
26520 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
26530 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
26540 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
26550 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
26560 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
26570 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
26580 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
26590 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
265a0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
265b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
265c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
265d0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
265e0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
265f0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
26600 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
26610 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
26620 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
26630 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
26640 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
26650 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
26660 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
26670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
26680 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
26690 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
266a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
266b0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
266c0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
266d0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
266e0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
266f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
26700 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
26710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
26720 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
26730 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
26740 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
26750 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
26760 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
26770 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
26780 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
26790 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
267a0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
267b0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
267c0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
267d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
267e0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
267f0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
26800 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
26810 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
26820 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
26830 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ^A pointer to an
26840 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
26850 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c object.** is al
26860 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
26870 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 eter to [applica
26880 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
26890 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
268a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d The application-
268b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
268c0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
268d0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 ion will pass th
268e0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 is.** pointer th
268f0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 rough into calls
26900 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
26910 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 ult_int | sqlite
26920 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 3_result()],.**
26930 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
26940 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b te_context()], [
26950 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
26960 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 a()],.** [sqlite
26970 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
26980 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 dle()], [sqlite3
26990 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c _get_auxdata()],
269a0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 .** and/or [sqli
269b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
269c0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
269d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f truct sqlite3_co
269e0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f ntext sqlite3_co
269f0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ntext;../*.** CA
26a00 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 PI3REF: Binding
26a10 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 Values To Prepar
26a20 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a ed Statements.**
26a30 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
26a40 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
26a50 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
26a60 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
26a70 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
26a80 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
26a90 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
26aa0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
26ab0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e ding}.**.** ^(In
26ac0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
26ad0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f nt text input to
26ae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26af0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 e_v2()] and its
26b00 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 variants,.** lit
26b10 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 erals may be rep
26b20 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 laced by a [para
26b30 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 meter] that matc
26b40 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f hes one of follo
26b50 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 wing.** template
26b60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
26b70 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
26b80 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
26b90 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 :VVV.** <li> @V
26ba0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 VV.** <li> $VVV
26bb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
26bc0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 In the templates
26bd0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 above, NNN repr
26be0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 esents an intege
26bf0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e r literal,.** an
26c00 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 d VVV represents
26c10 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 an alphanumeric
26c20 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 identifier.)^
26c30 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 ^The values of t
26c40 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hese.** paramete
26c50 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 rs (also called
26c60 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 "host parameter
26c70 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 names" or "SQL p
26c80 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 arameters").** c
26c90 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 an be set using
26ca0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
26cb0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 _*() routines de
26cc0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a fined here..**.*
26cd0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
26ce0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
26cf0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
26d00 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 utines is always
26d10 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
26d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
26d30 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 mt] object retur
26d40 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c ned from.** [sql
26d50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
26d60 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
26d70 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ts..**.** ^The s
26d80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
26d90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
26da0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
26db0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e to be set..** ^
26dc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c The leftmost SQL
26dd0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
26de0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e n index of 1. ^
26df0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
26e00 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
26e10 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
26e20 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
26e30 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
26e40 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
26e50 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
26e60 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
26e70 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
26e80 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 * ^The index for
26e90 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
26ea0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 s can be looked
26eb0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 up using the.**
26ec0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
26ed0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
26ee0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e API if desired.
26ef0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 ^The index.**
26f00 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d for "?NNN" param
26f10 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c eters is the val
26f20 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 ue of NNN..** ^T
26f30 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 he NNN value mus
26f40 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 t be between 1 a
26f50 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f nd the [sqlite3_
26f60 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 limit()].** para
26f70 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 meter [SQLITE_LI
26f80 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
26f90 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 BER] (default va
26fa0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a lue: 999)..**.**
26fb0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 ^The third argu
26fc0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 ment is the valu
26fd0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 e to bind to the
26fe0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
26ff0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 * ^(In those rou
27000 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 tines that have
27010 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e a fourth argumen
27020 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 t, its value is
27030 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
27040 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 bytes in the pa
27050 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 rameter. To be
27060 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 clear: the value
27070 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
27080 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 r of <u>bytes</u
27090 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 > in the value,
270a0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
270b0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a f characters.)^.
270c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 ** ^If the fourt
270d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
270e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
270f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 () or sqlite3_bi
27100 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 nd_text16().** i
27110 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
27120 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
27130 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 he string is.**
27140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
27150 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 tes up to the fi
27160 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
27170 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 tor..** If the f
27180 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
27190 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
271a0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 blob() is negati
271b0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ve, then.** the
271c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
271d0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e fined..** If a n
271e0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 on-negative four
271f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
27200 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 provided to sqli
27210 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a te3_bind_text().
27220 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
27230 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e nd_text16() then
27240 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
27250 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 must be the byte
27260 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 offset.** where
27270 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 the NUL termina
27280 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 tor would occur
27290 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 assuming the str
272a0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 ing were NUL.**
272b0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 terminated. If
272c0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 any NUL characte
272d0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 rs occur at byte
272e0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 offsets less th
272f0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 an .** the value
27300 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
27310 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 arameter then th
27320 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
27330 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a ng value will.**
27340 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
27350 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 d NULs. The res
27360 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f ult of expressio
27370 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 ns involving str
27380 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 ings.** with emb
27390 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e edded NULs is un
273a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
273b0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
273c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 nt to sqlite3_bi
273d0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 nd_blob(), sqlit
273e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 e3_bind_text(),
273f0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 and.** sqlite3_b
27400 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 ind_text16() is
27410 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
27420 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
27430 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 the BLOB or.** s
27440 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 tring after SQLi
27450 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 te has finished
27460 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 with it. ^The d
27470 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
27480 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 led.** to dispos
27490 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
274a0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 string even if
274b0 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 the call to sqli
274c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c te3_bind_blob(),
274d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 .** sqlite3_bind
274e0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 _text(), or sqli
274f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
27500 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 ) fails. .** ^I
27510 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
27520 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 ment is.** the s
27530 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 pecial value [SQ
27540 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 LITE_STATIC], th
27550 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 en SQLite assume
27560 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e s that the.** in
27570 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 formation is in
27580 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 static, unmanage
27590 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 d space and does
275a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
275b0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 freed..** ^If th
275c0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
275d0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
275e0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
275f0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
27600 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
27610 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
27620 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
27630 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
27640 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
27650 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
27660 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
27670 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
27680 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
27690 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
276a0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
276b0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
276c0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 zeroes. ^A zer
276d0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
276e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
276f0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
27700 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
27710 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
27720 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
27730 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
27740 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
27750 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
27760 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
27770 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
27780 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
27790 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
277a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
277b0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
277c0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
277d0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 es..** ^A negati
277e0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
277f0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
27800 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
27810 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e th BLOB..**.** ^
27820 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 If any of the sq
27830 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
27840 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
27850 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
27860 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 ointer.** for th
27870 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
27880 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 ement] or with a
27890 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
278a0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a ent for which.**
278b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
278c0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 ] has been calle
278d0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 d more recently
278e0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 than [sqlite3_re
278f0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 set()],.** then
27900 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 the call will re
27910 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 turn [SQLITE_MIS
27920 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 USE]. If any sq
27930 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a lite3_bind_().**
27940 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 routine is pass
27950 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ed a [prepared s
27960 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
27970 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
27980 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 d, the.** result
27990 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
279a0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 d probably harmf
279b0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 ul..**.** ^Bindi
279c0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 ngs are not clea
279d0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 red by the [sqli
279e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 te3_reset()] rou
279f0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e tine..** ^Unboun
27a00 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
27a10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
27a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
27a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 sqlite3_bind_*
27a40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
27a50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
27a60 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 uccess or an.**
27a70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
27a80 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
27a90 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ong..** ^[SQLITE
27aa0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
27ab0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
27ac0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
27ad0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
27ae0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
27af0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
27b00 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
27b10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
27b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
27b30 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
27b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
27b50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
27b60 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
27b70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
27b80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
27b90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
27ba0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
27bb0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
27bc0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
27bd0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
27be0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f sqlite3_bind_do
27bf0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
27c00 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 t*, int, double)
27c10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
27c20 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 nd_int(sqlite3_s
27c30 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b tmt*, int, int);
27c40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
27c50 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f d_int64(sqlite3_
27c60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 stmt*, int, sqli
27c70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 te3_int64);.int
27c80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c sqlite3_bind_nul
27c90 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c l(sqlite3_stmt*,
27ca0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 int);.int sqlit
27cb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c e3_bind_text(sql
27cc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
27cd0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
27ce0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
27cf0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
27d00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 3_bind_text16(sq
27d10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
27d20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
27d30 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
27d40 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
27d50 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
27d60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
27d70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
27d80 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
27d90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
27da0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
27db0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a int, int n);../*
27dc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
27dd0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 mber Of SQL Para
27de0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 meters.**.** ^Th
27df0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
27e00 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
27e10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
27e20 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
27e30 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
27e40 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
27e50 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
27e60 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
27e70 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
27e80 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
27e90 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
27ea0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
27eb0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
27ec0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
27ed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
27ee0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
27ef0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
27f00 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
27f10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f .**.** ^(This ro
27f20 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 utine actually r
27f30 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
27f40 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
27f50 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 (rightmost).** p
27f60 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c arameter. For al
27f70 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f l forms except ?
27f80 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 NNN, this will c
27f90 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 orrespond to the
27fa0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e .** number of un
27fb0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e ique parameters.
27fc0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 If parameters
27fd0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d of the ?NNN form
27fe0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 are used,.** th
27ff0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 ere may be gaps
28000 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a in the list.)^.*
28010 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
28020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
28030 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
28040 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
28050 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
28060 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
28070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
28080 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
28090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
280a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
280b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
280c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
280d0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
280e0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a ost Parameter.**
280f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
28100 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28110 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 name(P,N) interf
28120 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 ace returns.** t
28130 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e he name of the N
28140 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 -th [SQL paramet
28150 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 er] in the [prep
28160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
28170 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 P..** ^(SQL para
28180 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
28190 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 rm "?NNN" or ":A
281a0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
281b0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 "$AAA".** have
281c0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 a name which is
281d0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e the string "?NNN
281e0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
281f0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
28200 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
28210 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
28220 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ds, the initial
28230 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 ":" or "$" or "@
28240 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 " or "?".** is i
28250 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 ncluded as part
28260 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a of the name.)^.*
28270 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 * ^Parameters of
28280 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 the form "?" wi
28290 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e thout a followin
282a0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e g integer have n
282b0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 o name.** and ar
282c0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 e referred to as
282d0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 "nameless" or "
282e0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 anonymous parame
282f0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ters"..**.** ^Th
28300 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 e first host par
28310 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
28320 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e dex of 1, not 0.
28330 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 .**.** ^If the v
28340 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 alue N is out of
28350 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 range or if the
28360 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 N-th parameter
28370 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 is.** nameless,
28380 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
28390 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 urned. ^The ret
283a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a urned string is.
283b0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 ** always in UTF
283c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
283d0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
283e0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f rameter was.** o
283f0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 riginally specif
28400 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e ied as UTF-16 in
28410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28420 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 e16()] or.** [sq
28430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28440 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
28450 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
28460 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
28470 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
28480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
28490 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
284a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
284b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
284c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 ndex()]..*/.cons
284d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
284e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
284f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
28500 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *, int);../*.**
28510 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 CAPI3REF: Index
28520 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 Of A Parameter W
28530 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 ith A Given Name
28540 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 .**.** ^Return t
28550 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
28560 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 QL parameter giv
28570 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 en its name. ^T
28580 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 he.** index valu
28590 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 e returned is su
285a0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 itable for use a
285b0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
285c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
285d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
285e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e sqlite3_bind()].
285f0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 ^A zero.** is
28600 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d returned if no m
28610 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 atching paramete
28620 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 r is found. ^Th
28630 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e e parameter.** n
28640 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 ame must be give
28650 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 n in UTF-8 even
28660 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 if the original
28670 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 statement.** was
28680 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 prepared from U
28690 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 TF-16 text using
286a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
286b0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
286c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
286d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
286e0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
286f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
28700 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
28710 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
28720 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
28730 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
28740 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
28750 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
28760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
28770 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
28780 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 e);../*.** CAPI3
28790 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 REF: Reset All B
287a0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 indings On A Pre
287b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
287c0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 **.** ^Contrary
287d0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
287e0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
287f0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
28800 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
28810 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
28820 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
28830 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
28840 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
28850 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
28860 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f to reset all ho
28870 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f st parameters to
28880 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
28890 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
288a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
288b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
288c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
288d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
288e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 ult Set.**.** ^R
288f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
28900 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
28910 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
28920 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
28930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28940 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 ment]. ^This rou
28950 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
28960 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
28970 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
28980 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
28990 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
289a0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
289b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
289c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 so: [sqlite3_dat
289d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e a_count()].*/.in
289e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
289f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
28a00 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
28a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
28a20 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
28a30 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a Result Set.**.**
28a40 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
28a50 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
28a60 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
28a70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
28a80 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
28a90 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
28aa0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
28ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
28ac0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
28ad0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
28ae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
28af0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
28b00 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
28b10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
28b20 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
28b30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
28b40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
28b50 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
28b60 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ng. ^The first
28b70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
28b80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28b90 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
28ba0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
28bb0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
28bc0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
28bd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
28be0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
28bf0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
28c00 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
28c10 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 0..**.** ^The re
28c20 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
28c30 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
28c40 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
28c50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28c60 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
28c70 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
28c80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
28c90 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
28ca0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
28cb0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
28cc0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
28cd0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
28ce0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
28cf0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
28d00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
28d10 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
28d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
28d30 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
28d40 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
28d50 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
28d60 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c n..**.** ^If sql
28d70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
28d80 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
28d90 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
28da0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
28db0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
28dc0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
28dd0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
28de0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
28df0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
28e00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
28e10 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 ^The name of a r
28e20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
28e30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
28e40 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
28e50 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
28e60 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
28e70 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
28e80 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
28e90 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
28ea0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
28eb0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
28ec0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
28ed0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
28ee0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
28ef0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
28f00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
28f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
28f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28f30 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 nt N);.const voi
28f40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
28f50 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
28f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
28f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
28f80 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 Source Of Data
28f90 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c In A Query Resul
28fa0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
28fb0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
28fc0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
28fd0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 mine the databas
28fe0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a e, table, and.**
28ff0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
29000 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e at is the origin
29010 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 of a particular
29020 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
29030 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 n.** [SELECT] st
29040 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 atement..** ^The
29050 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
29060 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
29070 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
29080 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
29090 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 ither a UTF-8 or
290a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
290b0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f ^The _database_
290c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
290d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
290e0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
290f0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
29100 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
29110 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
29120 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
29130 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
29140 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 name..** ^The r
29150 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
29160 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 s valid until th
29170 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29180 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f ement] is destro
29190 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 yed.** using [sq
291a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
291b0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
291c0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
291d0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
291e0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
291f0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
29200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
29210 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
29220 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
29230 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
29240 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
29250 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
29260 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
29270 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 g..**.** ^The na
29280 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
29290 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
292a0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
292b0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
292c0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
292d0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lumn..**.** ^The
292e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
292f0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
29300 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 ces is a [prepar
29310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
29320 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
29330 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
29340 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
29350 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
29360 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
29370 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
29380 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
29390 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
293a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
293b0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d left-most colum
293c0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f n is column 0 fo
293d0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
293e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
293f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
29400 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
29410 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
29420 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
29430 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
29440 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
29450 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
29460 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
29470 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 rn.** NULL. ^Th
29480 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
29490 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
294a0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
294b0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
294c0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 ** occurs. ^Oth
294d0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
294e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
294f0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
29500 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a abase, table,.**
29510 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 or column that
29520 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
29530 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
29540 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 d from..**.** ^A
29550 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
29560 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
29570 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 ose whose names
29580 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 end with "16" re
29590 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
295a0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 ncoded strings a
295b0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e nd the other fun
295c0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
295d0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 F-8..**.** ^Thes
295e0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 e APIs are only
295f0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
29600 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
29610 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
29620 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
29630 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
29640 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
29650 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 symbol..**.** I
29660 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
29670 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
29680 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
29690 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
296a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
296b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
296c0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
296d0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
296e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
296f0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
29700 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
29710 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
29720 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
29730 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
29740 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
29750 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
29760 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
29770 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
29780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29790 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
297a0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
297b0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
297c0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
297d0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
297e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
297f0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
29800 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
29810 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
29820 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
29830 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
29840 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
29850 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
29860 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
29870 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
29880 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
29890 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
298a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
298b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
298c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
298d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
298e0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
298f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
29900 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
29910 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
29920 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
29930 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
29940 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
29950 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
29960 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
29970 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
29980 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
29990 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
299a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
299b0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
299c0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
299d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
299e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
299f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
29a00 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
29a10 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
29a20 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
29a30 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
29a40 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
29a50 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
29a60 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
29a70 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
29a80 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
29a90 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
29aa0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
29ab0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
29ac0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
29ad0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
29ae0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
29af0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
29b00 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
29b10 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
29b20 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
29b30 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
29b40 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
29b50 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
29b60 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
29b70 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
29b80 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
29b90 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
29ba0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
29bb0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
29bc0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
29bd0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
29be0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
29bf0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
29c00 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
29c10 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
29c20 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
29c30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
29c40 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
29c50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
29c60 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
29c70 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
29c80 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
29c90 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
29ca0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
29cb0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
29cc0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
29cd0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
29ce0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
29cf0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
29d00 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
29d10 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
29d20 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
29d30 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
29d40 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
29d50 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
29d60 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
29d70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
29d80 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
29d90 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
29da0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
29db0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
29dc0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
29dd0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
29de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
29df0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
29e00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
29e10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
29e20 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
29e30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
29e40 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
29e50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
29e60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
29e70 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
29e80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29e90 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
29ea0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
29eb0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
29ec0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
29ed0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29ee0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
29ef0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
29f00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
29f10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
29f20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
29f30 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
29f40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
29f50 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
29f60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
29f70 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
29f80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
29f90 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
29fa0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
29fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
29fc0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
29fd0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
29fe0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
29ff0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
2a000 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
2a010 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
2a020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2a030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2a040 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2a050 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
2a060 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2a070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a080 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2a090 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
2a0a0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
2a0b0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
2a0c0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2a0d0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
2a0e0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
2a0f0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2a100 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
2a110 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
2a120 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
2a130 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2a140 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
2a150 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
2a160 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
2a170 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
2a180 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
2a190 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
2a1a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
2a1b0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
2a1c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2a1d0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
2a1e0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
2a1f0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
2a200 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2a210 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2a220 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
2a230 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
2a240 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2a250 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2a260 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
2a270 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
2a280 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
2a290 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
2a2a0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
2a2b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
2a2c0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
2a2d0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
2a2e0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2a2f0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
2a300 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
2a310 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
2a320 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2a330 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
2a340 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
2a350 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
2a360 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
2a370 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
2a380 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
2a390 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
2a3a0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
2a3b0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
2a3c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2a3d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
2a3e0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2a3f0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
2a400 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2a410 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2a420 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
2a430 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
2a440 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
2a450 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
2a460 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2a470 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
2a480 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
2a490 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
2a4a0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
2a4b0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
2a4c0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
2a4d0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
2a4e0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
2a4f0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
2a500 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
2a510 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
2a520 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
2a530 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
2a540 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
2a550 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
2a560 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
2a570 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
2a580 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
2a590 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2a5a0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
2a5b0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
2a5c0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
2a5d0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
2a5e0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
2a5f0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
2a600 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
2a610 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
2a620 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
2a630 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
2a640 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
2a650 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
2a660 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
2a670 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
2a680 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
2a690 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2a6a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
2a6b0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
2a6c0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
2a6d0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2a6e0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
2a6f0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
2a700 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
2a710 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
2a720 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
2a730 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
2a740 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
2a750 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2a760 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
2a770 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2a780 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
2a790 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
2a7a0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
2a7b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
2a7c0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
2a7d0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
2a7e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
2a7f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
2a800 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
2a810 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
2a820 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
2a830 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
2a840 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
2a850 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
2a860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2a870 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
2a880 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
2a890 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2a8a0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
2a8b0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
2a8c0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
2a8d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2a8e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
2a8f0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
2a900 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
2a910 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
2a920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a930 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
2a940 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
2a950 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
2a960 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
2a970 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
2a980 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
2a990 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
2a9a0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
2a9b0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
2a9c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2a9d0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
2a9e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
2a9f0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
2aa00 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
2aa10 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2aa20 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
2aa30 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
2aa40 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
2aa50 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
2aa60 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
2aa70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2aa80 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2aa90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
2aaa0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
2aab0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2aac0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
2aad0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2aae0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
2aaf0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
2ab00 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
2ab10 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
2ab20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
2ab30 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
2ab40 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
2ab50 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
2ab60 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
2ab70 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
2ab80 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
2ab90 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
2aba0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
2abb0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
2abc0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
2abd0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
2abe0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
2abf0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
2ac00 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
2ac10 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2ac20 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2ac30 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2ac40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2ac50 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2ac60 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2ac70 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2ac80 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2ac90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2aca0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2acb0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2acc0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2acd0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2ace0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2acf0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2ad00 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2ad10 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2ad20 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2ad30 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2ad40 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2ad50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2ad60 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2ad70 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2ad80 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2ad90 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2ada0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2adb0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2adc0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2add0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2ade0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2adf0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2ae00 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2ae10 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2ae20 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2ae30 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2ae40 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2ae50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2ae60 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2ae70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2ae80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2ae90 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2aea0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2aeb0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2aec0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2aed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2aee0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2aef0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2af00 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2af10 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2af20 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2af30 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2af40 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2af50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2af60 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2af70 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2af80 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
2af90 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2afa0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
2afb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
2afc0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 esult set.**.**
2afd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2afe0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 a_count(P) inter
2aff0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2b000 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
2b010 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 ns in the.** cur
2b020 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2b030 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 result set of [p
2b040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b050 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 t] P..** ^If pre
2b060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2b070 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 P does not have
2b080 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f results ready to
2b090 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 return.** (via
2b0a0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 calls to the [sq
2b0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
2b0c0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d | sqlite3_colum
2b0d0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 n_*()] of.** int
2b0e0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 erfaces) then sq
2b0f0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2b100 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a (P) returns 0..*
2b110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
2b120 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 ata_count(P) rou
2b130 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e tine also return
2b140 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 s 0 if P is a NU
2b150 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e LL pointer..** ^
2b160 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
2b170 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e _count(P) routin
2b180 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 e returns 0 if t
2b190 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
2b1a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
2b1b0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2b1c0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e d [SQLITE_DONE].
2b1d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ^The sqlite3_d
2b1e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 ata_count(P).**
2b1f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d will return non-
2b200 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 zero if previous
2b210 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2b220 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 3_step](P) retur
2b230 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 ned.** [SQLITE_R
2b240 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 OW], except in t
2b250 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b he case of the [
2b260 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 PRAGMA increment
2b270 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 al_vacuum].** wh
2b280 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 ere it always re
2b290 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 turns zero since
2b2a0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 each step of th
2b2b0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a at multi-step.**
2b2c0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 pragma returns
2b2d0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 0 columns of dat
2b2e0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 a..**.** See als
2b2f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 o: [sqlite3_colu
2b300 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 mn_count()].*/.i
2b310 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f nt sqlite3_data_
2b320 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2b330 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2b340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
2b350 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 damental Datatyp
2b360 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
2b370 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
2b380 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 * ^(Every value
2b390 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
2b3a0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
2b3b0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
2b3c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2b3d0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
2b3e0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
2b3f0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
2b400 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
2b410 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
2b420 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
2b430 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
2b440 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
2b450 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
2b460 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
2b470 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
2b480 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
2b490 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
2b4a0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
2b4b0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
2b4c0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
2b4d0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
2b4e0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
2b4f0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
2b500 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
2b510 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
2b520 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
2b530 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
2b540 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
2b550 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
2b560 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
2b570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
2b580 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
2b590 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
2b5a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2b5b0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
2b5c0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
2b5d0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
2b5e0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
2b5f0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
2b600 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
2b610 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
2b620 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
2b630 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
2b640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b650 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
2b660 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b rom A Query.** K
2b670 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
2b680 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
2b690 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
2b6a0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
2b6b0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e "result set" in
2b6c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
2b6d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2b6e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2b6f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
2b700 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
2b710 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
2b720 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
2b730 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
2b740 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
2b750 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
2b760 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
2b770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2b780 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
2b790 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
2b7a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
2b7b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
2b7c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2b7d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2b7e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
2b7f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
2b800 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2b810 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2b820 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
2b830 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
2b840 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
2b850 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
2b860 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
2b870 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
2b880 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
2b890 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
2b8a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2b8b0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
2b8c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
2b8d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2b8e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
2b8f0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2b900 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
2b910 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
2b920 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
2b930 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
2b940 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
2b950 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
2b960 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
2b970 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
2b980 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
2b990 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
2b9a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2b9b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2b9c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
2b9d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2b9e0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
2b9f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
2ba00 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
2ba10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2ba20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
2ba30 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
2ba40 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
2ba50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
2ba60 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
2ba70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
2ba80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
2ba90 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
2baa0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
2bab0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
2bac0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
2bad0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2bae0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
2baf0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2bb00 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
2bb10 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2bb20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2bb30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2bb40 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
2bb50 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
2bb60 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
2bb70 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
2bb80 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
2bb90 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
2bba0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2bbb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2bbc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2bbd0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
2bbe0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
2bbf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
2bc00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
2bc10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
2bc20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
2bc30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
2bc40 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
2bc50 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
2bc60 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
2bc70 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
2bc80 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
2bc90 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
2bca0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
2bcb0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
2bcc0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
2bcd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2bce0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
2bcf0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
2bd00 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
2bd10 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
2bd20 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
2bd30 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
2bd40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
2bd50 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
2bd60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2bd70 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2bd80 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
2bd90 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
2bda0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
2bdb0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
2bdc0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
2bdd0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
2bde0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
2bdf0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
2be00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2be10 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
2be20 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
2be30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
2be40 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
2be50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2be60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2be70 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
2be80 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
2be90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2bea0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
2beb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2bec0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
2bed0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
2bee0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
2bef0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
2bf00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2bf10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2bf20 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2bf30 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2bf40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2bf50 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
2bf60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
2bf70 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
2bf80 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
2bf90 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2bfa0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
2bfb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2bfc0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
2bfd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2bfe0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
2bff0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c000 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
2c010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
2c020 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
2c030 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
2c040 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
2c050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c060 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2c070 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2c080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2c090 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2c0a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2c0b0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
2c0c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2c0d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2c0e0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
2c0f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
2c100 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
2c110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2c120 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
2c130 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2c140 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
2c150 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2c160 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
2c170 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
2c180 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
2c190 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
2c1a0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
2c1b0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
2c1c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2c1d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
2c1e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2c1f0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
2c200 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2c210 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2c220 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2c230 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
2c240 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2c250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c260 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
2c270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c280 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
2c290 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
2c2a0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
2c2b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
2c2c0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
2c2d0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
2c2e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
2c2f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2c300 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
2c310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c320 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
2c330 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
2c340 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
2c350 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
2c360 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
2c370 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
2c380 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2c390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2c3a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
2c3b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
2c3c0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
2c3d0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
2c3e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
2c3f0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
2c400 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
2c410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2c420 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
2c430 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
2c440 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2c450 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 .** ^The object
2c460 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2c470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2c480 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
2c490 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2c4a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2c4b0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
2c4c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2c4d0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
2c4e0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
2c4f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
2c500 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
2c510 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2c520 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
2c530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2c540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2c550 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
2c560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c570 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
2c580 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
2c590 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
2c5a0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
2c5b0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
2c5c0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
2c5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2c5e0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
2c5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
2c600 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
2c610 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
2c620 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
2c630 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
2c640 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
2c650 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
2c660 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 propriate. ^For
2c670 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
2c680 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
2c690 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
2c6a0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
2c6b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
2c6c0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
2c6d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
2c6e0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
2c6f0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
2c700 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
2c710 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 omatically. ^(T
2c720 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 he following tab
2c730 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 le details the c
2c740 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 onversions.** th
2c750 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a at are applied:.
2c760 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
2c770 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
2c780 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
2c790 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 <th> Internal<br
2c7a0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 >Type <th> Reque
2c7b0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 sted<br>Type <th
2c7c0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a > Conversion.**
2c7d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
2c7e0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
2c7f0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
2c800 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
2c810 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
2c820 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
2c830 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
2c840 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2c850 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
2c860 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2c870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2c880 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2c890 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2c8a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2c8b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2c8c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
2c8d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
2c8e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
2c8f0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
2c900 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
2c910 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
2c920 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
2c930 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
2c940 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
2c950 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
2c960 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2c970 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
2c980 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
2c990 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
2c9a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2c9b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
2c9c0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 float to intege
2c9d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 r.** <tr><td> F
2c9e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
2c9f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2ca00 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2ca10 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
2ca20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2ca30 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2ca40 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e Same as FLOAT->
2ca50 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
2ca60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 TEXT <td> I
2ca70 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 NTEGER <td> Us
2ca80 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
2ca90 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2caa0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2cab0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 > Use atof().**
2cac0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
2cad0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2cae0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a <td> No change.
2caf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2cb00 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 B <td> INTEGE
2cb10 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
2cb20 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 to TEXT then us
2cb30 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
2cb40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
2cb50 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2cb60 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
2cb70 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 T then use atof(
2cb80 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
2cb90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 LOB <td> TE
2cba0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 XT <td> Add a
2cbb0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2cbc0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f if needed.** </
2cbd0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
2cbe0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
2cbf0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
2cc00 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
2cc10 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
2cc20 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
2cc30 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
2cc40 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
2cc50 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
2cc60 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
2cc70 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
2cc80 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
2cc90 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
2cca0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
2ccb0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
2ccc0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
2ccd0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
2cce0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
2ccf0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
2cd00 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
2cd10 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
2cd20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
2cd30 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
2cd40 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
2cd50 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
2cd60 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
2cd70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2cd80 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
2cd90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
2cda0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
2cdb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2cdc0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
2cdd0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
2cde0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
2cdf0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
2ce00 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
2ce10 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
2ce20 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
2ce30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
2ce40 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2ce50 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
2ce60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ce70 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
2ce80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ce90 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
2cea0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
2ceb0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
2cec0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
2ced0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
2cee0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
2cef0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
2cf00 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
2cf10 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
2cf20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2cf30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
2cf40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2cf50 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
2cf60 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
2cf70 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
2cf80 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
2cf90 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
2cfa0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2cfb0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
2cfc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2cfd0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
2cfe0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2cff0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
2d000 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
2d010 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
2d020 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
2d030 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
2d040 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f </ul>.**.** ^Co
2d050 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
2d060 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
2d070 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
2d080 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
2d090 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
2d0a0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
2d0b0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
2d0c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
2d0d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
2d0e0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
2d0f0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
2d100 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 references will
2d110 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
2d120 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
2d130 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
2d140 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
2d150 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
2d160 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
2d170 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
2d180 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
2d190 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
2d1a0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
2d1b0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
2d1c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 d..**.** The saf
2d1d0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 est and easiest
2d1e0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 to remember poli
2d1f0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 cy is to invoke
2d200 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
2d210 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 * in one of the
2d220 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a following ways:.
2d230 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c **.** <ul>.** <
2d240 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
2d250 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 n_text() followe
2d260 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2d270 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
2d280 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
2d290 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
2d2a0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2d2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2d2c0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
2d2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2d2e0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 xt16() followed
2d2f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2d300 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e n_bytes16()</li>
2d310 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
2d320 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2d330 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 you should call
2d340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d350 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 ext(),.** sqlite
2d360 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
2d370 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
2d380 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 mn_text16() firs
2d390 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 t to force the r
2d3a0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 esult.** into th
2d3b0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 e desired format
2d3c0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 , then invoke sq
2d3d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2d3e0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 es() or.** sqlit
2d3f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2d400 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6() to find the
2d410 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 size of the resu
2d420 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 lt. Do not mix
2d430 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 calls.** to sqli
2d440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2d450 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2d460 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 umn_blob() with
2d470 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
2d480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2d490 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 16(), and do not
2d4a0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 mix calls to sq
2d4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2d4c0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 t16().** with ca
2d4d0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
2d4e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a olumn_bytes()..*
2d4f0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 *.** ^The pointe
2d500 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 rs returned are
2d510 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 valid until a ty
2d520 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 pe conversion oc
2d530 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 curs as.** descr
2d540 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 ibed above, or u
2d550 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ntil [sqlite3_st
2d560 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2d570 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
2d580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2d590 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e ze()] is called.
2d5a0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 ^The memory sp
2d5b0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 ace used to hold
2d5c0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 strings.** and
2d5d0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 BLOBs is freed a
2d5e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 utomatically. D
2d5f0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 o <b>not</b> pas
2d600 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 s the pointers r
2d610 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 eturned.** [sqli
2d620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2d630 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c )], [sqlite3_col
2d640 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 umn_text()], etc
2d650 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 . into.** [sqlit
2d660 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
2d670 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 * ^(If a memory
2d680 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
2d690 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
2d6a0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
2d6b0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 any.** of these
2d6c0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 routines, a def
2d6d0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 ault value is re
2d6e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 turned. The def
2d6f0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 ault value.** is
2d700 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 either the inte
2d710 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 ger 0, the float
2d720 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
2d730 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 0.0, or a NULL.
2d740 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 ** pointer. Sub
2d750 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
2d760 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
2d770 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e e()] will return
2d780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
2d790 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 M].)^.*/.const v
2d7a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2d7b0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 umn_blob(sqlite3
2d7c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2d7d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2d7e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
2d7f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2d800 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
2d810 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2d820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2d830 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c int iCol);.doubl
2d840 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2d850 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
2d860 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2d870 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
2d880 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 lumn_int(sqlite3
2d890 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2d8a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
2d8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d8c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
2d8d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d8e0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
2d8f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
2d900 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
2d910 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2d920 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2d930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2d940 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
2d950 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
2d960 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2d970 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 n_type(sqlite3_s
2d980 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2d990 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a .sqlite3_value *
2d9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2d9b0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2d9c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
2d9d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d9e0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
2d9f0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
2da00 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ect.**.** ^The s
2da10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2da20 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
2da30 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
2da40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2da50 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 ment]..** ^If th
2da60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
2da70 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 aluation of the
2da80 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e statement encoun
2da90 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a tered no errors.
2daa0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 ** or if the sta
2dab0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 tement is never
2dac0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 been evaluated,
2dad0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e then sqlite3_fin
2dae0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a alize() returns.
2daf0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e ** SQLITE_OK. ^
2db00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2db10 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 nt evaluation of
2db20 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 statement S fai
2db30 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c led, then.** sql
2db40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2db50 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 returns the app
2db60 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
2db70 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
2db80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
2db90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
2dba0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
2dbb0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 ) routine can be
2dbc0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 called at any p
2dbd0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 oint during.** t
2dbe0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 he life cycle of
2dbf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2dc00 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f ment] S:.** befo
2dc10 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 re statement S i
2dc20 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 s ever evaluated
2dc30 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f , after.** one o
2dc40 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 r more calls to
2dc50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2dc60 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 ], or after any
2dc70 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 call.** to [sqli
2dc80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 te3_step()] rega
2dc90 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
2dca0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 r or not the sta
2dcb0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f tement has.** co
2dcc0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
2dcd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 n..**.** ^Invoki
2dce0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ng sqlite3_final
2dcf0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 ize() on a NULL
2dd00 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 pointer is a har
2dd10 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a mless no-op..**.
2dd20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
2dd30 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 on must finalize
2dd40 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 every [prepared
2dd50 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f statement] in o
2dd60 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a rder to avoid.**
2dd70 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e resource leaks.
2dd80 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f It is a grievo
2dd90 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 us error for the
2dda0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
2ddb0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 try to use.** a
2ddc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ddd0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
2dde0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 been finalized.
2ddf0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 Any use of a pr
2de00 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
2de10 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
2de20 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 been finalized
2de30 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e can result in un
2de40 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 defined and.** u
2de50 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
2de60 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 ior such as segf
2de70 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 aults and heap c
2de80 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e orruption..*/.in
2de90 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 t sqlite3_finali
2dea0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
2deb0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2dec0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
2ded0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2dee0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
2def0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
2df00 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 set() function i
2df10 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 s called to rese
2df20 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 t a [prepared st
2df30 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
2df40 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ct back to its i
2df50 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 nitial state, re
2df60 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 ady to be re-exe
2df70 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 cuted..** ^Any S
2df80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
2df90 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
2dfa0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
2dfb0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
2dfc0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2dfd0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
2dfe0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
2dff0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
2e000 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
2e010 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2e020 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2e030 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
2e040 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
2e050 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
2e060 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
2e070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2e080 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 t] S.** back to
2e090 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
2e0a0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a its program..**
2e0b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
2e0c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
2e0d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2e0e0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 ] for the.** [pr
2e0f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e100 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
2e110 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
2e120 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f LITE_DONE],.** o
2e130 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 r if [sqlite3_st
2e140 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 ep(S)] has never
2e150 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c before been cal
2e160 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 led on S,.** the
2e170 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
2e180 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 (S)] returns [SQ
2e190 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
2e1a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
2e1b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
2e1c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
2e1d0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
2e1e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2e1f0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
2e200 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c or, then.** [sql
2e210 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
2e220 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
2e230 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
2e240 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b e]..**.** ^The [
2e250 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
2e260 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
2e270 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
2e280 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 values.** of any
2e290 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2e2a0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
2e2b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2e2c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
2e2d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 int sqlite3_rese
2e2e0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2e2f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2e300 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
2e310 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
2e320 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
2e330 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
2e340 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
2e350 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
2e360 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
2e370 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2e380 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
2e390 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
2e3a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2e3b0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ons}.**.** ^Thes
2e3c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c e functions (col
2e3d0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 lectively known
2e3e0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 as "function cre
2e3f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 ation routines")
2e400 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 .** are used to
2e410 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e add SQL function
2e420 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 s or aggregates
2e430 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 or to redefine t
2e440 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f he behavior.** o
2e450 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 f existing SQL f
2e460 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
2e470 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c egates. The onl
2e480 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 y differences be
2e490 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 tween.** these r
2e4a0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 outines are the
2e4b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 text encoding ex
2e4c0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 pected for.** th
2e4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2e4e0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 er (the name of
2e4f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 the function bei
2e500 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 ng created).** a
2e510 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 nd the presence
2e520 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 or absence of a
2e530 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
2e540 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ack for.** the a
2e550 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
2e560 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
2e570 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
2e580 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
2e590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2e5a0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
2e5b0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
2e5c0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e to be added. ^
2e5d0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f If an applicatio
2e5e0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e n uses more than
2e5f0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a one database.**
2e600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e connection then
2e610 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2e620 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2e630 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
2e640 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 .** to each data
2e650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2e660 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
2e670 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 * ^The second pa
2e680 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e rameter is the n
2e690 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ame of the SQL f
2e6a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 unction to be cr
2e6b0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 eated or.** rede
2e6c0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e fined. ^The len
2e6d0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
2e6e0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
2e6f0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 5 bytes in a UTF
2e700 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 -8.** representa
2e710 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 tion, exclusive
2e720 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d of the zero-term
2e730 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 inator. ^Note t
2e740 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 hat the name.**
2e750 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 length limit is
2e760 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 in UTF-8 bytes,
2e770 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e not characters n
2e780 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e or UTF-16 bytes.
2e790 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d .** ^Any attem
2e7a0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
2e7b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
2e7c0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
2e7d0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
2e7e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 LITE_MISUSE] bei
2e7f0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a ng returned..**.
2e800 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 ** ^The third pa
2e810 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
2e820 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
2e830 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
2e840 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
2e850 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
2e860 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 te takes. ^If th
2e870 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
2e880 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c -1, then the SQL
2e890 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2e8a0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 aggregate may ta
2e8b0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 ke any number of
2e8c0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 arguments betwe
2e8d0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d en 0 and the lim
2e8e0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 it.** set by [sq
2e8f0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 lite3_limit]([SQ
2e900 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2e910 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 ION_ARG]). If t
2e920 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
2e930 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 meter is less th
2e940 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 an -1 or greater
2e950 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 than 127 then t
2e960 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a he behavior is.*
2e970 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2e980 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 ** ^The fourth p
2e990 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 arameter, eTextR
2e9a0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 ep, specifies wh
2e9b0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 at.** [SQLITE_UT
2e9c0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 F8 | text encodi
2e9d0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e ng] this SQL fun
2e9e0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f ction prefers fo
2e9f0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 r.** its paramet
2ea00 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 ers. Every SQL
2ea10 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
2ea20 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 ntation must be
2ea30 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 able to work.**
2ea40 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d with UTF-8, UTF-
2ea50 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 16le, or UTF-16b
2ea60 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 e. But some imp
2ea70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 lementations may
2ea80 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 be.** more effi
2ea90 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 cient with one e
2eaa0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f ncoding than ano
2eab0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 ther. ^An appli
2eac0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e cation may.** in
2ead0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 voke sqlite3_cre
2eae0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f ate_function() o
2eaf0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
2eb00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 _function16() mu
2eb10 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
2eb20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 with the same fu
2eb30 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 nction but with
2eb40 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 different values
2eb50 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a of eTextRep..**
2eb60 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
2eb70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
2eb80 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
2eb90 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
2eba0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
2ebb0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
2ebc0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
2ebd0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
2ebe0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
2ebf0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 n..** If there i
2ec00 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 s only a single
2ec10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
2ec20 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 hich does not ca
2ec30 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 re what text.**
2ec40 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
2ec50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 , then the fourt
2ec60 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c h argument shoul
2ec70 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 d be [SQLITE_ANY
2ec80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 ]..**.** ^(The f
2ec90 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
2eca0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
2ecb0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
2ecc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
2ecd0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
2ece0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
2ecf0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
2ed00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
2ed10 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a er_data()].)^.**
2ed20 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 .** ^The sixth,
2ed30 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 seventh and eigh
2ed40 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 th parameters, x
2ed50 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 Func, xStep and
2ed60 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 xFinal, are.** p
2ed70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e ointers to C-lan
2ed80 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 guage functions
2ed90 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
2eda0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2edb0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e or.** aggregate.
2edc0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 ^A scalar SQL f
2edd0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
2ede0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
2edf0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
2ee00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
2ee10 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 ; NULL pointers
2ee20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 must be passed a
2ee30 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
2ee40 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
2ee50 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 ters. ^An aggreg
2ee60 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
2ee70 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
2ee80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 lementation of x
2ee90 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
2eea0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e al and NULL poin
2eeb0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 ter must be pass
2eec0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 ed for xFunc. ^T
2eed0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 o delete an exis
2eee0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 ting.** SQL func
2eef0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
2ef00 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 e, pass NULL poi
2ef10 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 nters for all th
2ef20 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ree function.**
2ef30 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
2ef40 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 ^(If the ninth
2ef50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2ef60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2ef70 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 tion_v2() is not
2ef80 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 NULL,.** then i
2ef90 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 t is destructor
2efa0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
2efb0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
2efc0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 . .** The destru
2efd0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 ctor is invoked
2efe0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f when the functio
2eff0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 n is deleted, ei
2f000 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a ther by being.**
2f010 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 overloaded or w
2f020 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
2f030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
2f040 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 es.)^.** ^The de
2f050 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f structor is also
2f060 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 invoked if the
2f070 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
2f080 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f090 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a on_v2() fails..*
2f0a0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 * ^When the dest
2f0b0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
2f0c0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 of the tenth par
2f0d0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 ameter is invoke
2f0e0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 d, it.** is pass
2f0f0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 ed a single argu
2f100 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
2f110 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c copy of the appl
2f120 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a ication data .**
2f130 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 pointer which w
2f140 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 as the fifth par
2f150 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
2f160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2f170 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 n_v2()..**.** ^I
2f180 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
2f190 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
2f1a0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
2f1b0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
2f1c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
2f1d0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
2f1e0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
2f1f0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
2f200 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
2f210 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
2f220 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
2f230 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 codings. ^SQLit
2f240 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 e will use.** th
2f250 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f260 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 that most close
2f270 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 ly matches the w
2f280 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a ay in which the.
2f290 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
2f2a0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e is used. ^A fun
2f2b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
2f2c0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
2f2d0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
2f2e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
2f2f0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
2f300 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
2f310 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
2f320 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
2f330 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f Arg. ^A functio
2f340 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
2f350 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
2f360 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
2f370 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
2f380 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
2f390 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
2f3a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2f3b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
2f3c0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
2f3d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
2f3e0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
2f3f0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 ifference is bet
2f400 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 ween UTF16le and
2f410 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 UTF16be.** is a
2f420 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 closer match th
2f430 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
2f440 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
2f450 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a difference is.*
2f460 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 * between UTF8 a
2f470 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 nd UTF16..**.**
2f480 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 ^Built-in functi
2f490 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c ons may be overl
2f4a0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 oaded by new app
2f4b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2f4c0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
2f4d0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f * ^An applicatio
2f4e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2f4f0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
2f500 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
2f510 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
2f520 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
2f530 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
2f540 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
2f550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f560 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
2f570 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
2f580 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2f590 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
2f5a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
2f5b0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ing..*/.int sqli
2f5c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f5d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
2f5e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
2f5f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
2f600 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
2f610 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
2f620 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
2f630 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
2f640 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2f650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2f660 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
2f670 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2f680 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2f690 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2f6a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
2f6b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 3_context*).);.i
2f6c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2f6d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
2f6e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
2f6f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
2f700 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
2f710 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
2f720 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
2f730 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
2f740 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
2f750 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2f760 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2f770 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
2f780 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2f790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2f7a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
2f7b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
2f7c0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
2f7d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f7e0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ion_v2(. sqlite
2f7f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
2f800 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
2f810 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
2f820 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
2f830 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
2f840 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
2f850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
2f860 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
2f870 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
2f880 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
2f890 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
2f8a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
2f8b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
2f8c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a ite3_context*),.
2f8d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
2f8e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a )(void*).);../*.
2f8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 ** CAPI3REF: Tex
2f900 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a t Encodings.**.*
2f910 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
2f920 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
2f930 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
2f940 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
2f950 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
2f960 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
2f970 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
2f980 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
2f990 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
2f9a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
2f9b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
2f9c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
2f9d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
2f9e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
2f9f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
2fa00 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
2fa10 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
2fa20 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
2fa30 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
2fa40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2fa50 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a unction only */.
2fa60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2fa70 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
2fa80 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
2fa90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
2faa0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
2fab0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
2fac0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
2fad0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
2fae0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
2faf0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
2fb00 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
2fb10 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
2fb20 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
2fb30 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
2fb40 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
2fb50 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
2fb60 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
2fb70 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
2fb80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
2fb90 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
2fba0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
2fbb0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 unctions. To he
2fbc0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f lp encourage peo
2fbd0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ple to avoid.**
2fbe0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 using these func
2fbf0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f tions, we are no
2fc00 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 t going to tell
2fc10 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f you what they do
2fc20 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
2fc30 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
2fc40 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
2fc50 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
2fc60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
2fc70 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
2fc80 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
2fc90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
2fca0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
2fcb0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
2fcc0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2fcd0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
2fce0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
2fcf0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
2fd00 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
2fd10 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
2fd20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
2fd30 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
2fd40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2fd50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
2fd60 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
2fd70 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
2fd80 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
2fd90 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
2fda0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
2fdb0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
2fdc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
2fdd0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
2fde0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
2fdf0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
2fe00 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
2fe10 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 lues.**.** The C
2fe20 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d -language implem
2fe30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 entation of SQL
2fe40 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
2fe50 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a gregates uses.**
2fe60 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 this set of int
2fe70 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
2fe80 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 to access the pa
2fe90 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f rameter values o
2fea0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f n.** the functio
2feb0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a n or aggregate..
2fec0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
2fed0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
2fee0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
2fef0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
2ff00 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
2ff10 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2ff20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
2ff30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
2ff40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
2ff50 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
2ff60 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
2ff70 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
2ff80 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
2ff90 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
2ffa0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2ffb0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
2ffc0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
2ffd0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
2ffe0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2fff0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
30000 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
30010 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30020 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
30030 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
30040 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
30050 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
30060 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
30070 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
30080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
30090 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
300a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
300b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
300c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
300d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
300e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
300f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
30100 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
30110 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
30120 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
30130 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
30140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
30150 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
30160 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
30170 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
30180 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
30190 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
301a0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
301b0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 that these rout
301c0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
301d0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
301e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
301f0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
30200 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
30210 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
30220 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
30230 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
30240 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
30250 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
30260 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
30270 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
30280 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
30290 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
302a0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
302b0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
302c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
302d0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
302e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
302f0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
30300 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
30310 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
30320 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
30330 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
30340 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
30350 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
30360 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
30370 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
30380 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
30390 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
303a0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
303b0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
303c0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
303d0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
303e0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
303f0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
30400 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
30410 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
30420 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
30430 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
30440 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
30450 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
30460 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
30470 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
30480 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
30490 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
304a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
304b0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
304c0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
304d0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
304e0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
304f0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
30500 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
30510 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
30520 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
30530 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
30540 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
30550 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
30560 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
30570 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
30580 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
30590 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
305a0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
305b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
305c0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
305d0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
305e0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
305f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
30600 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
30610 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
30620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
30630 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
30640 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
30650 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
30660 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
30670 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
30680 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
30690 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
306a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
306b0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
306c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
306d0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f arameters..*/.co
306e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
306f0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 3_value_blob(sql
30700 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
30710 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
30720 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 bytes(sqlite3_va
30730 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
30740 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
30750 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
30760 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
30770 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
30780 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
30790 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
307a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
307b0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ue*);.sqlite3_in
307c0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
307d0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
307e0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 value*);.const u
307f0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
30800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30810 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
30820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
30830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30840 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
30850 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
30860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30870 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 xt16le(sqlite3_v
30880 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
30890 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
308a0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
308b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
308c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
308d0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
308e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
308f0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
30900 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
30910 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
30920 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
30930 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
30940 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 ontext.**.** Imp
30950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
30960 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
30970 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 nctions use this
30980 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 .** routine to a
30990 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 llocate memory f
309a0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
309b0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 state..**.** ^T
309c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
309d0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
309e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
309f0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
30a00 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 ed .** for a par
30a10 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 ticular aggregat
30a20 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 e function, SQLi
30a30 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 te.** allocates
30a40 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 N of memory, zer
30a50 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d oes out that mem
30a60 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
30a70 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
30a80 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e the new memory.
30a90 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 ^On second and
30aa0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
30ab0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
30ac0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
30ad0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
30ae0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
30af0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 on instance,.**
30b00 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
30b10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 is returned. Sq
30b20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
30b30 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 context() is nor
30b40 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 mally.** called
30b50 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e once for each in
30b60 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
30b70 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 xStep callback a
30b80 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c nd then one.** l
30b90 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 ast time when th
30ba0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
30bb0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e k is invoked. ^
30bc0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 (When no rows ma
30bd0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 tch.** an aggreg
30be0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 ate query, the x
30bf0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 Step() callback
30c00 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
30c10 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 function.** imp
30c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
30c30 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 ever called and
30c40 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c xFinal() is call
30c50 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e ed exactly once.
30c60 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 .** In those cas
30c70 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 es, sqlite3_aggr
30c80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
30c90 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 might be called
30ca0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 for the.** first
30cb0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 time from withi
30cc0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a n xFinal().)^.**
30cd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30ce0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
30cf0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
30d00 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
30d10 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a ointer if N is.*
30d20 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 * less than or e
30d30 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 qual to zero or
30d40 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
30d50 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 cate error occur
30d60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 s..**.** ^(The a
30d70 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 mount of space a
30d80 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
30d90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
30da0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a ntext(C,N) is.**
30db0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
30dc0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f he N parameter o
30dd0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 n first successf
30de0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 ul call. Changi
30df0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 ng the.** value
30e00 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 of N in subseque
30e10 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
30e20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
30e30 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a text() within.**
30e40 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 the same aggreg
30e50 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 ate function ins
30e60 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 tance will not r
30e70 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 esize the memory
30e80 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 .** allocation.)
30e90 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ^.**.** ^SQLite
30ea0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
30eb0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ees the memory a
30ec0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 llocated by .**
30ed0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
30ee0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e e_context() when
30ef0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 the aggregate q
30f00 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
30f10 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
30f20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 parameter must b
30f30 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a e a copy of the.
30f40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
30f50 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 ext | SQL functi
30f60 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 on context] that
30f70 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
30f80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
30f90 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 e xStep or xFina
30fa0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 l callback routi
30fb0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ne that implemen
30fc0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ts the aggregate
30fd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a .** function..**
30fe0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
30ff0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
31000 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
31010 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
31020 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 the aggregate S
31030 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
31040 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
31050 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 *sqlite3_aggrega
31060 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 te_context(sqlit
31070 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
31080 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a nBytes);../*.**
31090 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 CAPI3REF: User
310a0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f Data For Functio
310b0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ns.**.** ^The sq
310c0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
310d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
310e0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
310f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 the pointer tha
31100 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 t was the pUserD
31110 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 ata parameter (t
31120 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
31130 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
31140 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
31150 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
31160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
31170 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
31180 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
31190 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
311a0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
311b0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
311c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
311d0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
311e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
311f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
31200 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 which.** the app
31210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31220 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
31230 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ning..*/.void *s
31240 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
31250 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
31260 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
31270 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
31280 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e nnection For Fun
31290 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 ctions.**.** ^Th
312a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e sqlite3_contex
312b0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e t_db_handle() in
312c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
312d0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
312e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
312f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
31300 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 tion] (the 1st p
31310 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
31320 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
31330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
31340 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
31350 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
31360 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
31370 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
31380 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
31390 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
313a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f ned function..*/
313b0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
313c0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
313d0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
313e0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
313f0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
31400 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a Auxiliary Data.
31410 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 **.** The follow
31420 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ing two function
31430 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
31440 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
31450 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f tions to.** asso
31460 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 ciate metadata w
31470 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
31480 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
31490 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
314a0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
314b0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
314c0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
314d0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
314e0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
314f0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
31500 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
31510 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 ociated metadata
31520 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
31530 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
31540 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
31550 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
31560 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
31570 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
31580 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
31590 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
315a0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
315b0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
315c0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
315d0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
315e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 with the SQL va
315f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
31600 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
31610 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e sion.** pattern.
31620 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 The compiled r
31630 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
31640 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 n can be reused
31650 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 on multiple.** i
31660 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
31670 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
31680 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 so that the orig
31690 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 inal pattern str
316a0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ing.** does not
316b0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d need to be recom
316c0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e piled on each in
316d0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 vocation..**.**
316e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
316f0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
31700 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
31710 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
31720 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
31730 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 ated by the sqli
31740 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
31750 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 ) function with
31760 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
31770 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 .** value to the
31780 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
31790 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e ined function. ^
317a0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 If no metadata h
317b0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 as been ever.**
317c0 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
317d0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 Nth argument of
317e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f the function, o
317f0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 r if the corresp
31800 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 onding.** functi
31810 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 on parameter has
31820 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 changed since t
31830 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 he meta-data was
31840 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 set,.** then sq
31850 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
31860 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 a() returns a NU
31870 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
31880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
31890 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
318a0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 erface saves the
318b0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 metadata.** poi
318c0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 nted to by its 3
318d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 rd parameter as
318e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 the metadata for
318f0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 the N-th.** arg
31900 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 ument of the app
31910 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31920 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 function. Subs
31930 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
31940 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 to sqlite3_get_a
31950 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 uxdata() might r
31960 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c eturn this data,
31970 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f if it has.** no
31980 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 t been destroyed
31990 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e ..** ^If it is n
319a0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
319b0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
319c0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 destructor.** fu
319d0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 nction given by
319e0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
319f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 r to sqlite3_set
31a00 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a _auxdata() on.**
31a10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 the metadata wh
31a20 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
31a30 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
31a40 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a rameter changes.
31a50 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 ** or when the S
31a60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
31a70 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 pletes, whicheve
31a80 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
31a90 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 *.** SQLite is f
31aa0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 ree to call the
31ab0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 destructor and d
31ac0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 rop metadata on
31ad0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 any.** parameter
31ae0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e of any function
31af0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e at any time. ^
31b00 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 The only guarant
31b10 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 ee is that.** th
31b20 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c e destructor wil
31b30 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f l be called befo
31b40 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 re the metadata
31b50 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a is dropped..**.*
31b60 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c * ^(In practice,
31b70 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 metadata is pre
31b80 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
31b90 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
31ba0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
31bb0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
31bc0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
31bd0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
31be0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
31bf0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 ues and [paramet
31c00 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ers].)^.**.** Th
31c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
31c20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
31c30 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
31c40 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
31c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
31c60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
31c70 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 d *sqlite3_get_a
31c80 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
31c90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
31ca0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 .void sqlite3_se
31cb0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
31cc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
31cd0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 N, void*, void (
31ce0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a *)(void*));.../*
31cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
31d00 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 nstants Defining
31d10 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 Special Destruc
31d20 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a tor Behavior.**.
31d30 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 ** These are spe
31d40 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 cial values for
31d50 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 the destructor t
31d60 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e hat is passed in
31d70 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c as the.** final
31d80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 argument to rou
31d90 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
31da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
31db0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 )]. ^If the des
31dc0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d tructor.** argum
31dd0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 ent is SQLITE_ST
31de0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 ATIC, it means t
31df0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
31e00 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 pointer is const
31e10 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 ant.** and will
31e20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 never change. I
31e30 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 t does not need
31e40 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e to be destroyed.
31e50 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 ^The.** SQLITE
31e60 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 _TRANSIENT value
31e70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
31e80 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b content will lik
31e90 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ely change in.**
31ea0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 the near future
31eb0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 and that SQLite
31ec0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 should make its
31ed0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
31ee0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
31ef0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 ent before retur
31f00 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ning..**.** The
31f10 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 typedef is neces
31f20 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f sary to work aro
31f30 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 und problems in
31f40 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 certain.** C++ c
31f50 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 ompilers. See t
31f60 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a icket #2191..*/.
31f70 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
31f80 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
31f90 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a r_type)(void*);.
31fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
31fb0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c TATIC ((sql
31fc0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
31fd0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 type)0).#define
31fe0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
31ff0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
32000 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 tructor_type)-1)
32010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32020 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 : Setting The Re
32030 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 sult Of An SQL F
32040 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 unction.**.** Th
32050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
32060 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 used by the xFu
32070 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c nc or xFinal cal
32080 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 lbacks that.** i
32090 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e mplement SQL fun
320a0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
320b0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b gates. See.** [
320c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
320d0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
320e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
320f0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
32100 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
32110 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
32120 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
32130 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 s work very much
32140 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d like the [param
32150 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 eter binding] fa
32160 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 mily of.** funct
32170 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e ions used to bin
32180 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 d values to host
32190 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 parameters in p
321a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
321b0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 ts..** Refer to
321c0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 the [SQL paramet
321d0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f er] documentatio
321e0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
321f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
32200 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32210 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 _result_blob() i
32220 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
32230 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
32240 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
32250 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
32260 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 to be the BLOB
32270 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 whose content is
32280 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 pointed.** to b
32290 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 y the second par
322a0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 ameter and which
322b0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 is N bytes long
322c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
322d0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
322e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
322f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
32300 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
32310 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
32320 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
32330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
32340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
32350 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
32360 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
32370 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
32380 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
32390 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
323a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
323b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
323c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
323d0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
323e0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
323f0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
32400 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32410 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
32420 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
32430 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
32440 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
32450 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
32460 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32470 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
32480 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32490 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
324a0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
324b0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
324c0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
324d0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
324e0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
324f0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
32500 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
32510 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
32520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32530 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
32540 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
32550 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
32560 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
32570 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 sage. ^SQLite i
32580 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 nterprets the er
32590 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 ror.** message s
325a0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
325b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
325c0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c ) as UTF-8. ^SQL
325d0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
325e0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
325f0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
32600 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
32610 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
32620 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e * byte order. ^
32630 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
32640 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
32650 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
32660 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
32670 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
32680 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e is negative then
32690 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 SQLite takes as
326a0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
326b0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 ssage all text u
326c0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 p through the fi
326d0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
326e0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
326f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
32700 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
32710 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 _error() or.** s
32720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32730 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e ror16() is non-n
32740 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
32750 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d ite takes that m
32760 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f any.** bytes (no
32770 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 t characters) fr
32780 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
32790 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f eter as the erro
327a0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 r message..** ^T
327b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
327c0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
327d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
327e0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
327f0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
32800 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
32810 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
32820 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
32830 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
32840 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
32850 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
32860 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
32870 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
32880 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
32890 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 out harm..** ^Th
328a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
328b0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 _error_code() fu
328c0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 nction changes t
328d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a he error code.**
328e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
328f0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 ite as a result
32900 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 of an error in a
32910 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 function. ^By
32920 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 default,.** the
32930 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 error code is SQ
32940 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 LITE_ERROR. ^A
32950 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
32960 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
32970 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
32980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
32990 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 rror16() resets
329a0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 the error code t
329b0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a o SQLITE_ERROR..
329c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
329d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
329e0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 toobig() interfa
329f0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
32a00 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 to throw an.**
32a10 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 error indicating
32a20 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f that a string o
32a30 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f r BLOB is too lo
32a40 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ng to represent.
32a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
32a60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
32a70 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 _nomem() interfa
32a80 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
32a90 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 to throw an.**
32aa0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 error indicating
32ab0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 that a memory a
32ac0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 llocation failed
32ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
32ae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 ite3_result_int(
32af0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
32b00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
32b10 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
32b20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32b30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
32b40 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 he 32-bit signed
32b50 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
32b60 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
32b70 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 nd argument..**
32b80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
32b90 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
32ba0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
32bb0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
32bc0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
32bd0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
32be0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
32bf0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
32c00 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
32c10 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
32c20 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
32c30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
32c40 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 _null() interfac
32c50 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
32c60 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
32c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
32c80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
32c90 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a o be NULL..**.**
32ca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
32cb0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c sult_text(), sql
32cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
32cd0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 16(),.** sqlite3
32ce0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
32cf0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f (), and sqlite3_
32d00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
32d10 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
32d20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 set the return v
32d30 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c alue of the appl
32d40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32d50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a function to be.*
32d60 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 * a text string
32d70 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 which is represe
32d80 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 nted as UTF-8, U
32d90 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
32da0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d e order,.** UTF-
32db0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 16 little endian
32dc0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 , or UTF-16 big
32dd0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 endian, respecti
32de0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 vely..** ^SQLite
32df0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 takes the text
32e00 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 result from the
32e10 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d application from
32e20 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 .** the 2nd para
32e30 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c meter of the sql
32e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
32e50 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a * interfaces..**
32e60 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 ^If the 3rd par
32e70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
32e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
32e90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
32ea0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
32eb0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
32ec0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d result text from
32ed0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
32ee0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 er.** through th
32ef0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
32f00 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 racter..** ^If t
32f10 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
32f20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
32f30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
32f40 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
32f50 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
32f60 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
32f70 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
32f80 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
32f90 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
32fa0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
32fb0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
32fc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32fd0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
32fe0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 result. If the
32ff0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
33000 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
33010 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 hen it.** must b
33020 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 e the byte offse
33030 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e t into the strin
33040 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 g where the NUL
33050 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 terminator would
33060 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 .** appear if th
33070 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e e string where N
33080 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 UL terminated.
33090 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 If any NUL chara
330a0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 cters occur.** i
330b0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 n the string at
330c0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 a byte offset th
330d0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 at is less than
330e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
330f0 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 3rd.** paramete
33100 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 r, then the resu
33110 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c lting string wil
33120 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 l contain embedd
33130 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a ed NULs and the.
33140 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 ** result of exp
33150 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 ressions operati
33160 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 ng on strings wi
33170 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 th embedded NULs
33180 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
33190 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
331a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
331b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
331c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
331d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
331e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f ult_blob is a no
331f0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
33200 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c then SQLite call
33210 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 s that.** functi
33220 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 on as the destru
33230 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 ctor on the text
33240 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
33250 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 when it has.** f
33260 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
33270 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
33280 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
33290 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
332a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
332b0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f interfaces or to
332c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
332d0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
332e0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
332f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 SQLITE_STATIC, t
33300 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 hen SQLite.** as
33310 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 sumes that the t
33320 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
33330 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e lt is in constan
33340 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 t space and does
33350 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 not.** copy the
33360 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
33370 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 parameter nor ca
33380 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ll a destructor
33390 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a on the content.*
333a0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 * when it has fi
333b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
333c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
333d0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
333e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
333f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
33400 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
33410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
33420 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
33430 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
33440 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 TE_TRANSIENT.**
33450 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 then SQLite make
33460 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
33470 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 result into spac
33480 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a e obtained from.
33490 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
334a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 _malloc()] befor
334b0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a e it returns..**
334c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
334d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
334e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
334f0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
33500 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
33510 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
33520 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
33530 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
33540 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
33550 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
33560 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
33570 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a ameter. ^The.**
33580 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33590 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
335a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
335b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
335c0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 alue].** so that
335d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
335e0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 lue] specified i
335f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 n the parameter
33600 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a may change or.**
33610 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
33620 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 after sqlite3_re
33630 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 sult_value() ret
33640 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 urns without har
33650 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 m..** ^A [protec
33660 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
33670 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c e] object may al
33680 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 ways be used whe
33690 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 re an.** [unprot
336a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
336b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 lue] object is r
336c0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 equired, so eith
336d0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 er.** kind of [s
336e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
336f0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 ject can be used
33700 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 with this inter
33710 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 face..**.** If t
33720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
33730 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 e called from wi
33740 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 thin the differe
33750 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 nt thread.** tha
33760 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 n the one contai
33770 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 ning the applica
33780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
33790 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 ction that recei
337a0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ved.** the [sqli
337b0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 te3_context] poi
337c0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 nter, the result
337d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
337e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
337f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c _result_blob(sql
33800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
33810 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
33820 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
33830 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
33840 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c esult_double(sql
33850 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 ite3_context*, d
33860 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c ouble);.void sql
33870 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33880 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
33890 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
338a0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
338b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
338c0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
338d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
338e0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
338f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33900 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 r_toobig(sqlite3
33910 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
33920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33930 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 error_nomem(sqli
33940 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
33950 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
33960 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 lt_error_code(sq
33970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
33980 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
33990 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 e3_result_int(sq
339a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
339b0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
339c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
339d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
339e0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
339f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
33a00 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 esult_null(sqlit
33a10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
33a20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
33a30 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 t_text(sqlite3_c
33a40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
33a50 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 har*, int, void(
33a60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
33a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33a80 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 text16(sqlite3_c
33a90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
33aa0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
33ab0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
33ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33ad0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
33ae0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
33af0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
33b00 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
33b10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33b20 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
33b30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
33b40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
33b50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
33b60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
33b70 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f t_value(sqlite3_
33b80 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
33b90 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 3_value*);.void
33ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
33bb0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
33bc0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 context*, int n)
33bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33be0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f F: Define New Co
33bf0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 llating Sequence
33c00 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 s.**.** ^These f
33c10 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 unctions add, re
33c20 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 move, or modify
33c30 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 a [collation] as
33c40 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
33c50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
33c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
33c70 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
33c80 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
33c90 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
33ca0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 he collation is
33cb0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a a UTF-8 string.*
33cc0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
33cd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
33ce0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 and sqlite3_cre
33cf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
33d00 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d ().** and a UTF-
33d10 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
33d20 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 ive byte order f
33d30 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
33d40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
33d50 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e .** ^Collation n
33d60 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 ames that compar
33d70 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e e equal accordin
33d80 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 g to [sqlite3_st
33d90 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a rnicmp()] are.**
33da0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
33db0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e e the same name.
33dc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 .**.** ^(The thi
33dd0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 rd argument (eTe
33de0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f xtRep) must be o
33df0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 ne of the consta
33e00 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 nts:.** <ul>.**
33e10 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
33e20 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8],.** <li> [SQL
33e30 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a ITE_UTF16LE],.**
33e40 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
33e50 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 F16BE],.** <li>
33e60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
33e70 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
33e80 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
33e90 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a ]..** </ul>)^.**
33ea0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 ^The eTextRep a
33eb0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e rgument determin
33ec0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 es the encoding
33ed0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 of strings passe
33ee0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c d.** to the coll
33ef0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
33f00 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 allback, xCallba
33f10 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c ck..** ^The [SQL
33f20 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b ITE_UTF16] and [
33f30 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
33f40 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 GNED] values for
33f50 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 eTextRep.** for
33f60 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 ce strings to be
33f70 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 UTF16 with nati
33f80 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
33f90 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
33fa0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
33fb0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 lue for eTextRep
33fc0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 forces strings
33fd0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 to begin.** on a
33fe0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 n even byte addr
33ff0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ess..**.** ^The
34000 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
34010 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 pArg, is an app
34020 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
34030 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 inter that is pa
34040 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 ssed.** through
34050 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
34060 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c ument to the col
34070 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
34080 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
34090 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
340a0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 ent, xCallback,
340b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
340c0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
340d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 nction..** ^Mult
340e0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 iple collating f
340f0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 unctions can be
34100 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
34110 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
34120 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 ut.** with diffe
34130 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 rent eTextRep pa
34140 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c rameters and SQL
34150 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 ite will use whi
34160 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 chever.** functi
34170 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 on requires the
34180 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
34190 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 data transformat
341a0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ion..** ^If the
341b0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 xCallback argume
341c0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 nt is NULL then
341d0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
341e0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c nction is.** del
341f0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c eted. ^When all
34200 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
34210 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 ions having the
34220 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 same name are de
34230 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 leted,.** that c
34240 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c ollation is no l
34250 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a onger usable..**
34260 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 .** ^The collati
34270 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c ng function call
34280 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
34290 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 with a copy of t
342a0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c he pArg .** appl
342b0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
342c0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 nter and with tw
342d0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 o strings in the
342e0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 encoding specif
342f0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 ied.** by the eT
34300 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e extRep argument.
34310 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 The collating
34320 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 function must re
34330 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 turn an.** integ
34340 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 er that is negat
34350 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f ive, zero, or po
34360 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 sitive.** if the
34370 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
34380 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 less than, equa
34390 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
343a0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
343b0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
343c0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 y. A collating
343d0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c function must al
343e0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 ways return the
343f0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 same answer.** g
34400 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e iven the same in
34410 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 puts. If two or
34420 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 more collating
34430 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 functions are re
34440 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 gistered.** to t
34450 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f he same collatio
34460 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 n name (using di
34470 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 fferent eTextRep
34480 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c values) then al
34490 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 l.** must give a
344a0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 n equivalent ans
344b0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 wer when invoked
344c0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 with equivalent
344d0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
344e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
344f0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 ion must obey th
34500 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 e following prop
34510 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a erties for all.*
34520 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 * strings A, B,
34530 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c and C:.**.** <ol
34540 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d >.** <li> If A==
34550 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 B then B==A..**
34560 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 <li> If A==B and
34570 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e B==C then A==C.
34580 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 .** <li> If A<
34590 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a ;B THEN B>A..
345a0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
345b0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 B and B<C the
345c0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f n A<C..** </o
345d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f l>.**.** If a co
345e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
345f0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 fails any of th
34600 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 e above constrai
34610 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 nts and that.**
34620 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
34630 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 on is registere
34640 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e d and used, then
34650 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
34660 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e SQLite.** is un
34670 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
34680 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 The sqlite3_crea
34690 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
346a0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c ) works like sql
346b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
346c0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 ation().** with
346d0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 the addition tha
346e0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 t the xDestroy c
346f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
34700 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a ed on pArg when.
34710 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 ** the collating
34720 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c function is del
34730 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 eted..** ^Collat
34740 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ing functions ar
34750 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 e deleted when t
34760 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
34770 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 en by later.** c
34780 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c alls to the coll
34790 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
347a0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e unctions or when
347b0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
347c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
347d0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 closed using [s
347e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e qlite3_close()].
347f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 .**.** ^The xDes
34800 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 troy callback is
34810 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c <u>not</u> call
34820 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 ed if the .** sq
34830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
34840 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 lation_v2() func
34850 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 tion fails. App
34860 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 lications that i
34870 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
34880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
34890 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f n_v2() with a no
348a0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 n-NULL xDestroy
348b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
348c0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 .** check the re
348d0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 turn code and di
348e0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 spose of the app
348f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
34900 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c inter.** themsel
34910 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 ves rather than
34920 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 expecting SQLite
34930 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 to deal with it
34940 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 for them..** Th
34950 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 is is different
34960 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 from every other
34970 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
34980 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 e. The inconsis
34990 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 tency .** is unf
349a0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e ortunate but can
349b0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 not be changed w
349c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
349d0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f backwards .** co
349e0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
349f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 ** See also: [s
34a00 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
34a10 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b _needed()] and [
34a20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
34a30 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a n_needed16()]..*
34a40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
34a50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a eate_collation(.
34a60 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
34a70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
34a80 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
34a90 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 p, . void *pArg
34aa0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
34ab0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
34ac0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
34ad0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 st void*).);.int
34ae0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
34af0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 collation_v2(.
34b00 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
34b10 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
34b20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
34b30 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a . void *pArg,.
34b40 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
34b50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
34b60 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
34b70 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 void*),. void(
34b80 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
34b90 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
34ba0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
34bb0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
34bc0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a . const void *
34bd0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 zName,. int eTe
34be0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
34bf0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
34c00 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
34c10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
34c20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
34c30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34c40 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 : Collation Need
34c50 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ed Callbacks.**.
34c60 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 ** ^To avoid hav
34c70 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
34c80 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
34c90 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
34ca0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
34cb0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
34cc0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
34cd0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
34ce0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
34cf0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
34d00 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 nection] to be i
34d10 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
34d20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c an undefined col
34d30 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
34d40 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a ce is required..
34d50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 **.** ^If the fu
34d60 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
34d70 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
34d80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
34d90 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
34da0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
34db0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
34dc0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
34dd0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
34de0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
34df0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e oded in UTF-8. ^
34e00 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 If sqlite3_colla
34e10 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 tion_needed16()
34e20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 is used,.** the
34e30 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 names are passed
34e40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 as UTF-16 in ma
34e50 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 chine native byt
34e60 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 e order..** ^A c
34e70 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
34e80 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
34e90 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c the existing col
34ea0 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 lation-needed ca
34eb0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 llback..**.** ^(
34ec0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
34ed0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 k is invoked, th
34ee0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
34ef0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 passed is a cop
34f00 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f y.** of the seco
34f10 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
34f20 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
34f30 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 _needed() or.**
34f40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
34f50 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 n_needed16(). T
34f60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
34f70 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
34f80 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
34f90 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
34fa0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
34fb0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
34fc0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
34fd0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
34fe0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 TF16LE], indicat
34ff0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 ing the most des
35000 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 irable form of t
35010 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 he collation.**
35020 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f sequence functio
35030 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 n required. The
35040 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
35050 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
35060 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 the.** required
35070 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
35080 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 nce.)^.**.** The
35090 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
350a0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 on should regist
350b0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 er the desired c
350c0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a ollation using.*
350d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
350e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 e_collation()],
350f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
35100 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 collation16()],
35110 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
35120 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
35130 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 v2()]..*/.int sq
35140 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
35150 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 needed(. sqlite
35160 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 3*, . void*, .
35170 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
35180 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
35190 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a tRep,const char*
351a0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
351b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
351c0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c d16(. sqlite3*,
351d0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 . void*,. voi
351e0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
351f0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
35200 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
35210 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f ..#ifdef SQLITE_
35220 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 HAS_CODEC./*.**
35230 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 Specify the key
35240 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 for an encrypted
35250 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 database. This
35260 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 routine should
35270 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 be.** called rig
35280 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ht after sqlite3
35290 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 _open()..**.** T
352a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
352b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
352c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
352d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
352e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
352f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
35300 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 3_key(. sqlite3
35310 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
35320 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
35330 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
35340 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
35350 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
35360 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 y /* The key
35370 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 */.);../*.** Ch
35380 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 ange the key on
35390 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 an open database
353a0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e . If the curren
353b0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f t database is no
353c0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 t.** encrypted,
353d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
353e0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 l encrypt it. I
353f0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 f pNew==0 or nNe
35400 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 w==0, the.** dat
35410 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 abase is decrypt
35420 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ed..**.** The co
35430 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
35440 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
35450 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
35460 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
35470 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
35480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b .int sqlite3_rek
35490 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
354a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
354b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
354c0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
354d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
354e0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
354f0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 /* The new ke
35500 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 y */.);../*.** S
35510 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 pecify the activ
35520 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 ation key for a
35530 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 SEE database. U
35540 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 nless .** activa
35550 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 ted, none of the
35560 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 SEE routines wi
35570 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 ll work..*/.void
35580 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 sqlite3_activat
35590 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 e_see(. const c
355a0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 har *zPassPhrase
355b0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 /* Activ
355c0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a ation phrase */.
355d0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 );.#endif..#ifde
355e0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
355f0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 CEROD./*.** Spec
35600 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 ify the activati
35610 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 on key for a CER
35620 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e OD database. Un
35630 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 less .** activat
35640 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 ed, none of the
35650 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 CEROD routines w
35660 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 ill work..*/.voi
35670 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 d sqlite3_activa
35680 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 te_cerod(. cons
35690 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 t char *zPassPhr
356a0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 ase /* Ac
356b0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 tivation phrase
356c0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a */.);.#endif../*
356d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 .** CAPI3REF: Su
356e0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 spend Execution
356f0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 For A Short Time
35700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
35710 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 e3_sleep() funct
35720 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 ion causes the c
35730 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f urrent thread to
35740 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 suspend executi
35750 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 on.** for at lea
35760 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d st a number of m
35770 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 illiseconds spec
35780 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 ified in its par
35790 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
357a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
357b0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 ystem does not s
357c0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 upport sleep req
357d0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 uests with.** mi
357e0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 llisecond time r
357f0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 esolution, then
35800 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 the time will be
35810 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a rounded up to.*
35820 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 * the nearest se
35830 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 cond. The number
35840 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
35850 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c of sleep actual
35860 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 ly.** requested
35870 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
35880 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
35890 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 urned..**.** ^SQ
358a0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
358b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 this interface b
358c0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 y calling the xS
358d0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 leep().** method
358e0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
358f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
35900 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 ject. If the xS
35910 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a leep() method.**
35920 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
35930 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 VFS is not imple
35940 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 mented correctly
35950 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 , or not impleme
35960 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 nted at.** all,
35970 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
35980 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 r of sqlite3_sle
35990 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 ep() may deviate
359a0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 from the descri
359b0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 ption.** in the
359c0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
359d0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 phs..*/.int sqli
359e0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a te3_sleep(int);.
359f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35a00 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c Name Of The Fol
35a10 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 der Holding Temp
35a20 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a orary Files.**.*
35a30 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 * ^(If this glob
35a40 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d al variable is m
35a50 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
35a60 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 a string which i
35a70 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
35a80 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 a folder (a.k.a
35a90 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 . directory), th
35aa0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 en all temporary
35ab0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 files.** create
35ac0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e d by SQLite when
35ad0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 using a built-i
35ae0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c n [sqlite3_vfs |
35af0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 VFS].** will be
35b00 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 placed in that
35b10 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 directory.)^ ^I
35b20 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a f this variable.
35b30 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
35b40 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
35b50 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 e performs a sea
35b60 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f rch for an appro
35b70 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 priate.** tempor
35b80 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f ary file directo
35b90 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 ry..**.** It is
35ba0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
35bb0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
35bc0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 variable in more
35bd0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 than one.** thr
35be0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 ead at a time.
35bf0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
35c00 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 o read or modify
35c10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
35c20 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 * if a [database
35c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
35c40 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 being used at th
35c50 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 e same time in a
35c60 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 separate.** thr
35c70 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e ead..** It is in
35c80 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 tended that this
35c90 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 variable be set
35ca0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 once.** as part
35cb0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 of process init
35cc0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 ialization and b
35cd0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 efore any SQLite
35ce0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f interface.** ro
35cf0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e utines have been
35d00 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 called and that
35d10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 this variable r
35d20 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a emain unchanged.
35d30 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a ** thereafter..*
35d40 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f *.** ^The [temp_
35d50 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
35d60 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 pragma] may modi
35d70 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
35d80 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 and cause.** it
35d90 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d to point to mem
35da0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
35db0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
35dc0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 c]. ^Furthermor
35dd0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f e,.** the [temp_
35de0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
35df0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 pragma] always a
35e00 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 ssumes that any
35e10 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 string.** that t
35e20 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 his variable poi
35e30 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 nts to is held i
35e40 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 n memory obtaine
35e50 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
35e60 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 te3_malloc] and
35e70 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 the pragma may a
35e80 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 ttempt to free t
35e90 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 hat memory.** us
35ea0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
35eb0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 e]..** Hence, if
35ec0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 this variable i
35ed0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 s modified direc
35ee0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 tly, either it s
35ef0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 hould be.** made
35f00 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f NULL or made to
35f10 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 point to memory
35f20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
35f30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a sqlite3_malloc].
35f40 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 ** or else the u
35f50 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f se of the [temp_
35f60 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
35f70 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 pragma] should b
35f80 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a e avoided..**.**
35f90 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
35fa0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
35fb0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
35fc0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
35fd0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
35fe0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
35ff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f [sqlite3_open] o
36000 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f r [sqlite3_open_
36010 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c v2]. Otherwise,
36020 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
36030 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
36040 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
36050 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
36060 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 fail. Here is
36070 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 an.** example of
36080 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 how to do this
36090 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 using C++ with t
360a0 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 he Windows Runti
360b0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b me:.**.** <block
360c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c quote><pre>.** L
360d0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 PCWSTR zPath = W
360e0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a indows::Storage:
360f0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 :ApplicationData
36100 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 ::Current->.** &
36110 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 nbsp; Tempor
36120 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d aryFolder->Path-
36130 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 >Data();.** char
36140 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41 zPathBuf[MA
36150 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b X_PATH + 1];
36160 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 .** memset(zPath
36170 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a Buf, 0, sizeof(z
36180 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 PathBuf));.** Wi
36190 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 deCharToMultiByt
361a0 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 e(CP_UTF8, 0, zP
361b0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 ath, -1, zPathBu
361c0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 f, sizeof(zPathB
361d0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 uf),.**
361e0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a NULL, NULL);.
361f0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f ** sqlite3_temp_
36200 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 directory = sqli
36210 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 te3_mprintf("%s"
36220 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 , zPathBuf);.**
36230 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
36240 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 te>.*/.SQLITE_EX
36250 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 TERN char *sqlit
36260 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
36270 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 y;../*.** CAPI3R
36280 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 EF: Name Of The
36290 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 Folder Holding D
362a0 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a atabase Files.**
362b0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c .** ^(If this gl
362c0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
362d0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
362e0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
362f0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
36300 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
36310 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 .a. directory),
36320 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 then all databas
36330 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 e files.** speci
36340 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 fied with a rela
36350 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e tive pathname an
36360 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 d created or acc
36370 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 essed by.** SQLi
36380 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 te when using a
36390 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 built-in windows
363a0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
363b0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 VFS] will be ass
363c0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 umed.** to be re
363d0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64 lative to that d
363e0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 irectory.)^ ^If
363f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 this variable is
36400 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
36410 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
36420 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c assumes that all
36430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 database files
36440 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 specified.** wit
36450 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 h a relative pat
36460 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69 hname are relati
36470 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e ve to the curren
36480 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 t directory.** f
36490 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20 or the process.
364a0 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 Only the window
364b0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20 s VFS makes use
364c0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a of this global.*
364d0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69 * variable; it i
364e0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65 s ignored by the
364f0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a unix VFS..**.**
36500 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61 Changing the va
36510 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69 lue of this vari
36520 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74 able while a dat
36530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36540 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 is.** open can
36550 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 result in a corr
36560 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a upt database..**
36570 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
36580 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
36590 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
365a0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 le in more than
365b0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 one.** thread at
365c0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 a time. It is
365d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
365e0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
365f0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 variable.** if a
36600 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
36610 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
36620 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 used at the same
36630 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 time in a separ
36640 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a ate.** thread..*
36650 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 * It is intended
36660 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
36670 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
36680 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
36690 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
366a0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
366b0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
366c0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
366d0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
366e0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 d and that this
366f0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 variable remain
36700 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 unchanged.** the
36710 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e reafter..**.** ^
36720 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f The [data_store_
36730 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
36740 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 ] may modify thi
36750 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 s variable and c
36760 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f ause.** it to po
36770 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 int to memory ob
36780 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
36790 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e ite3_malloc]. ^
367a0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 Furthermore,.**
367b0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f the [data_store_
367c0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
367d0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 ] always assumes
367e0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 that any string
367f0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 .** that this va
36800 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f riable points to
36810 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f is held in memo
36820 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
36830 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 .** [sqlite3_ma
36840 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 lloc] and the pr
36850 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 agma may attempt
36860 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 to free that me
36870 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 mory.** using [s
36880 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a qlite3_free]..**
36890 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 Hence, if this
368a0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 variable is modi
368b0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 fied directly, e
368c0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 ither it should
368d0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 be.** made NULL
368e0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 or made to point
368f0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
36900 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
36910 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 3_malloc].** or
36920 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 else the use of
36930 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f the [data_store_
36940 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
36950 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 ] should be avoi
36960 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ded..*/.SQLITE_E
36970 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 XTERN char *sqli
36980 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f te3_data_directo
36990 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ry;../*.** CAPI3
369a0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 REF: Test For Au
369b0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a to-Commit Mode.*
369c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
369d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a ocommit mode}.**
369e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
369f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 _get_autocommit(
36a00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
36a10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a rns non-zero or.
36a20 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 ** zero if the g
36a30 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f iven database co
36a40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 nnection is or i
36a50 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d s not in autocom
36a60 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 mit mode,.** res
36a70 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 pectively. ^Aut
36a80 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
36a90 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a on by default..*
36aa0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f * ^Autocommit mo
36ab0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 de is disabled b
36ac0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 y a [BEGIN] stat
36ad0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 ement..** ^Autoc
36ae0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 ommit mode is re
36af0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 -enabled by a [C
36b00 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 OMMIT] or [ROLLB
36b10 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 ACK]..**.** If c
36b20 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 ertain kinds of
36b30 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 errors occur on
36b40 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 a statement with
36b50 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 in a multi-state
36b60 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 ment.** transact
36b70 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c ion (errors incl
36b80 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 uding [SQLITE_FU
36b90 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 LL], [SQLITE_IOE
36ba0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f RR],.** [SQLITE_
36bb0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f NOMEM], [SQLITE_
36bc0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 BUSY], and [SQLI
36bd0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 TE_INTERRUPT]) t
36be0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 hen the.** trans
36bf0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 action might be
36c00 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
36c10 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 matically. The
36c20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 only way to.** f
36c30 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 ind out whether
36c40 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
36c50 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
36c60 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
36c70 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 after.** an err
36c80 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 or is to use thi
36c90 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a s function..**.*
36ca0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 * If another thr
36cb0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 ead changes the
36cc0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 autocommit statu
36cd0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 s of the databas
36ce0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
36cf0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 while this routi
36d00 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 ne is running, t
36d10 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
36d20 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 alue.** is undef
36d30 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ined..*/.int sql
36d40 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
36d50 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a mit(sqlite3*);..
36d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36d70 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 Find The Databas
36d80 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 e Handle Of A Pr
36d90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
36da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36db0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e te3_db_handle in
36dc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
36dd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
36de0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
36df0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b .** to which a [
36e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
36e10 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 nt] belongs. ^T
36e20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
36e30 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 nection].** retu
36e40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
36e50 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 db_handle is the
36e60 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
36e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 connection].** t
36e80 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 hat was the firs
36e90 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
36ea0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
36eb0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c epare_v2()] call
36ec0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 (or its variant
36ed0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 s) that was used
36ee0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 to.** create th
36ef0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 e statement in t
36f00 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a he first place..
36f10 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 */.sqlite3 *sqli
36f20 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 te3_db_handle(sq
36f30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
36f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
36f50 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 eturn The Filena
36f60 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73 me For A Databas
36f70 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a e Connection.**.
36f80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36f90 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 db_filename(D,N)
36fa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
36fb0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
36fc0 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 a filename.** as
36fd0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61 sociated with da
36fe0 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e tabase N of conn
36ff0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 ection D. ^The
37000 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 main database fi
37010 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 le.** has the na
37020 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 me "main". If t
37030 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63 here is no attac
37040 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f hed database N o
37050 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a n the database.*
37060 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 * connection D,
37070 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e or if database N
37080 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20 is a temporary
37090 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 or in-memory dat
370a0 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 abase, then.** a
370b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
370c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
370d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 ^The filename r
370e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
370f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 function is the
37100 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a output of the.**
37110 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d xFullPathname m
37120 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 ethod of the [VF
37130 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 S]. ^In other w
37140 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 ords, the filena
37150 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e me.** will be an
37160 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 absolute pathna
37170 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 me, even if the
37180 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a filename used.**
37190 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
371a0 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 abase originally
371b0 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65 was a URI or re
371c0 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e lative pathname.
371d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
371e0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e sqlite3_db_filen
371f0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ame(sqlite3 *db,
37200 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
37210 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
37220 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
37230 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 e if a database
37240 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a is read-only.**.
37250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37260 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 db_readonly(D,N)
37270 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
37280 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61 ns 1 if the data
37290 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e base N.** of con
372a0 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61 nection D is rea
372b0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 d-only, 0 if it
372c0 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f is read/write, o
372d0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 r -1 if N is not
372e0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
372f0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f a database on co
37300 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 nnection D..*/.i
37310 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 nt sqlite3_db_re
37320 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a adonly(sqlite3 *
37330 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a db, const char *
37340 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a zDbName);../*.**
37350 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
37360 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 the next prepare
37370 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d statement.**.*
37380 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
37390 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
373a0 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ter to the next
373b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
373c0 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 ent] after.** pS
373d0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 tmt associated w
373e0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
373f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 e connection] pD
37400 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 b. ^If pStmt is
37410 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 NULL.** then th
37420 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
37430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
37440 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 o the first prep
37450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
37460 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
37470 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 h the database c
37480 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 onnection pDb.
37490 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 ^If no prepared
374a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 statement.** sat
374b0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 isfies the condi
374c0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f tions of this ro
374d0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e utine, it return
374e0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 s NULL..**.** Th
374f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37500 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 ection] pointer
37510 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a D in a call to.*
37520 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f * [sqlite3_next_
37530 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 stmt(D,S)] must
37540 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e refer to an open
37550 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
37560 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 nection and in p
37570 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e articular must n
37580 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ot be a NULL poi
37590 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 nter..*/.sqlite3
375a0 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e _stmt *sqlite3_n
375b0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 ext_stmt(sqlite3
375c0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 *pDb, sqlite3_s
375d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
375e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
375f0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 mmit And Rollbac
37600 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 k Notification C
37610 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
37620 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d The sqlite3_comm
37630 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 it_hook() interf
37640 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
37650 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
37660 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b tion to be invok
37670 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 ed whenever a tr
37680 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f ansaction is [CO
37690 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 MMIT | committed
376a0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 ]..** ^Any callb
376b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
376c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
376d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
376e0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 k().** for the s
376f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
37700 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
37710 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 idden..** ^The s
37720 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
37730 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
37740 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
37750 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
37760 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 n to be invoked
37770 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
37780 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 action is [ROLLB
37790 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 ACK | rolled bac
377a0 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c k]..** ^Any call
377b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
377c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 evious call to s
377d0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
377e0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
377f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
37800 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
37810 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 erridden..** ^Th
37820 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
37830 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
37840 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 h to the callbac
37850 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 k..** ^If the ca
37860 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d llback on a comm
37870 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e it hook function
37880 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
37890 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 o,.** then the c
378a0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 ommit is convert
378b0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 ed into a rollba
378c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ck..**.** ^The s
378d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
378e0 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 ok(D,C,P) and sq
378f0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
37900 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 ook(D,C,P) funct
37910 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 ions.** return t
37920 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 he P argument fr
37930 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 om the previous
37940 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 call of the same
37950 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 function.** on
37960 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
37970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
37980 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a , or NULL for.**
37990 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
379a0 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f for each functio
379b0 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 n on D..**.** Th
379c0 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c e commit and rol
379d0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 lback hook callb
379e0 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65 acks are not ree
379f0 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 ntrant..** The c
37a00 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e allback implemen
37a10 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 tation must not
37a20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
37a30 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
37a40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
37a50 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
37a60 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 oked the callbac
37a70 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a k. Any actions.
37a80 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 ** to modify the
37a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
37aa0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 tion must be def
37ab0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 erred until afte
37ac0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 r the.** complet
37ad0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
37ae0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
37af0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
37b00 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 the commit.** or
37b10 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 rollback hook i
37b20 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 n the first plac
37b30 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 e..** Note that
37b40 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 running any othe
37b50 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
37b60 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 , including SELE
37b70 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a CT statements,.*
37b80 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c * or merely call
37b90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
37ba0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
37bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
37bc0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
37bd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
37be0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
37bf0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
37c00 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
37c10 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 graph..**.** ^Re
37c20 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c gistering a NULL
37c30 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
37c40 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e es the callback.
37c50 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 .**.** ^When the
37c60 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c commit hook cal
37c70 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
37c80 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 turns zero, the
37c90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 [COMMIT].** oper
37ca0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 ation is allowed
37cb0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 to continue nor
37cc0 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 mally. ^If the
37cd0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 commit hook.** r
37ce0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
37cf0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 then the [COMMI
37d00 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 T] is converted
37d10 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b into a [ROLLBACK
37d20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 ]..** ^The rollb
37d30 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f ack hook is invo
37d40 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 ked on a rollbac
37d50 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 k that results f
37d60 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 rom a commit.**
37d70 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e hook returning n
37d80 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 on-zero, just as
37d90 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 it would be wit
37da0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c h any other roll
37db0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 back..**.** ^For
37dc0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
37dd0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
37de0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
37df0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
37e00 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
37e10 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
37e20 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
37e30 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
37e40 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
37e50 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
37e60 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
37e70 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
37e80 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 .** ^The rollbac
37e90 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f k callback is no
37ea0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 t invoked if a t
37eb0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a ransaction is.**
37ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
37ed0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 olled back becau
37ee0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
37ef0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
37f00 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 osed..**.** See
37f10 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
37f20 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 3_update_hook()]
37f30 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 interface..*/.v
37f40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d oid *sqlite3_com
37f50 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 mit_hook(sqlite3
37f60 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 *, int(*)(void*)
37f70 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a , void*);.void *
37f80 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
37f90 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 _hook(sqlite3*,
37fa0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c void(*)(void *),
37fb0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
37fc0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 CAPI3REF: Data C
37fd0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 hange Notificati
37fe0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
37ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
38000 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e update_hook() in
38010 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
38020 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
38030 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 ction.** with th
38040 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38050 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 ection] identifi
38060 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
38070 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 argument.** to b
38080 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
38090 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 er a row is upda
380a0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 ted, inserted or
380b0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e deleted..** ^An
380c0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
380d0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
380e0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 l to this functi
380f0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 on.** for the sa
38100 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
38110 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
38120 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 dden..**.** ^The
38130 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
38140 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
38150 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f the function to
38160 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a invoke when a.*
38170 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 * row is updated
38180 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
38190 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 leted..** ^The f
381a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
381b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
381c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
381d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
381e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 to sqlite3_upda
381f0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 te_hook()..** ^T
38200 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 he second callba
38210 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f ck argument is o
38220 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
38230 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 SERT], [SQLITE_D
38240 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 ELETE],.** or [S
38250 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 QLITE_UPDATE], d
38260 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
38270 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 operation that c
38280 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 aused the callba
38290 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f ck.** to be invo
382a0 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ked..** ^The thi
382b0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 rd and fourth ar
382c0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 guments to the c
382d0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 allback contain
382e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a pointers to the.
382f0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 ** database and
38300 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 table name conta
38310 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 ining the affect
38320 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 ed row..** ^The
38330 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 final callback p
38340 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
38350 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 [rowid] of the r
38360 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 ow..** ^In the c
38370 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 ase of an update
38380 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 , this is the [r
38390 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 owid] after the
383a0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 update takes pla
383b0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ce..**.** ^(The
383c0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e update hook is n
383d0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ot invoked when
383e0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 internal system
383f0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f tables are.** mo
38400 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c dified (i.e. sql
38410 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 ite_master and s
38420 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e qlite_sequence).
38430 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 )^.**.** ^In the
38440 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 current impleme
38450 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 ntation, the upd
38460 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e ate hook.** is n
38470 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ot invoked when
38480 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 duplication rows
38490 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 are deleted bec
384a0 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f ause of an.** [O
384b0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 N CONFLICT | ON
384c0 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 CONFLICT REPLACE
384d0 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 ] clause. ^Nor
384e0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f is the update ho
384f0 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 ok.** invoked wh
38500 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 en rows are dele
38510 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 ted using the [t
38520 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 runcate optimiza
38530 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 tion]..** The ex
38540 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 ceptions defined
38550 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
38560 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ph might change
38570 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
38580 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
38590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 ..**.** The upda
385a0 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e te hook implemen
385b0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 tation must not
385c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
385d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
385e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
385f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
38600 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 oked the update
38610 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f hook. Any actio
38620 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
38630 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
38640 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
38650 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
38660 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
38670 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
38680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
38690 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
386a0 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f ed the update ho
386b0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ok..** Note that
386c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
386d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
386e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
386f0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
38700 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
38710 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
38720 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
38730 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
38740 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 raph..**.** ^The
38750 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
38760 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 hook(D,C,P) func
38770 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tion.** returns
38780 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 the P argument f
38790 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 rom the previous
387a0 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 call.** on the
387b0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
387c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 onnection] D, or
387d0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 NULL for.** the
387e0 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 first call on D
387f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
38800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
38810 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 mmit_hook()] and
38820 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 [sqlite3_rollba
38830 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e ck_hook()].** in
38840 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 terfaces.