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 74 65 73 20 74 6f 0a 2a ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 nt system. ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d RSION "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 VERS--".#define
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 D "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 rary instead of
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 ^(Cautious.**
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 on to.** verify
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 he macros in.**
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 the header, and
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 constant. The
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 DLL. ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 ON_NUMBER]. ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 ter to a string
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74 ction allows int
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: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 exes. When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 adsafe. When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d . Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 utexes incurs a
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d . But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 of SQLite that
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c E] flag. If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 NFIG_MUTEX]. ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 at setting made
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 ORDS: {database
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 sqlite3". It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 * pointer as an
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 object. The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 estructor. Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 y_timeout()] to
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 name but three)
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 _uint64 are the
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a lusive. ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 rn SQLITE_OK if
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79 ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 use a lot of C
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 interface runs
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 st.** argument.
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 ments. ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 ough to the 1st
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 ocation. ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 ipped. ^If the
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ning..**.** ^If
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ns SQLITE_ABORT
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 ult. ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e . ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 lback is a NULL
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 pointer. ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 ntry represents
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 s are evaluated
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c ** is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 ent text passed
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 into.** the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **errmsg
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 ine SQLITE_ROW
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 100 /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 QLITE_DONE
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 101 /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 ished executing
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 error codes}.**
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 time. Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 er be extended.
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 _READ (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 ITE_IOERR_WRITE
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 C (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 _IOERR_TRUNCATE
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 IOERR_FSTAT
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 ERR_RDLOCK
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 RR_DELETE
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 RR_BLOCKED
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 RR_NOMEM
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 RR_ACCESS
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 RR_LOCK
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 RR_CLOSE
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 RR_DIR_CLOSE
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 KED_SHAREDCACHE
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 0x00000001 /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 0x00000002 /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 0x00000004 /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 0x00000008 /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 0x00000010 /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 UTOPROXY
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 0x00000020 /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 0x00000100 /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 0x00000200 /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 0x00000400 /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 0x00000800 /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 0x00001000 /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 0x00002000 /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 0x00004000 /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 0x00008000 /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 0x00010000 /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 0x00020000 /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 RIVATECACHE
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 0x00040000 /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 racteristics of
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 ATOMIC4K
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 SEQUENTIAL
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 s a combination
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 at means to use
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 emantics..** If
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 ods element .**
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 inter, then the
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78 ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68 Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 at it failed. T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 nt to xSync may
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 C_FULL]. The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 choice is a Mac
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ync. The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 .** flag may be
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 lues to xLock()
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 _LOCK_NONE],.**
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 PENDING], or.**
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 ) increases the
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 lock. xUnlock()
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 kReservedLock()
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 s, is holding a
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 ile. It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f rface. The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 r opcode. The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 ucture that may
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 ich to.** write
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 return values.
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 with timeouts,
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 le locks. The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 ] less than 100
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 om xFileControl
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 e. The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 P_ATOMIC64K].**
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 er with zeros.
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f on;. int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 *);. int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 st);. int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e nt64 size);. in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 ags);. int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 int64 *pSize);.
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f );. int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 _file*, int op,
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 void *pArg);. i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 ;. int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 ;. /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 he lock (one of
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 USIVE]).** into
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 an integer that
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 s capability.**
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 esting and only
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 CKSTATE 1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 E 2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 PROXYFILE 3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 4../*.**
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 **.** The value
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 of the iVersion
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f SQLite. Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 d. Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 ame(). SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 until xClose()
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 ame if it needs
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 to remember the
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 e reason..** If
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 . Whenever the
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 it will also be
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 en_v2()]. Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 () opens a file
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 s to.** include
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 DONLY]. Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 ange the way it
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 * that does not
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 .** the open of
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 no-op. Writes
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 to this journal
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 ITE_IOERR. Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 s and writes in
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 gs to the xOpen
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f . The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 t for TEMP data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 bases, journals
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 which are both
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 XCL and O_CREAT
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 . The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 TE_OPEN_CREATE,
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 opened .** for
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 szOsFile bytes
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 pen. The xOpen
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 method does not
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e t fill it in. N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ote that.** the
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f or to NULL. xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 his even if the
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c open fails. SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 lid after xOpen
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 s.** or failure
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 Access() may be
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 adable. The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 e xRandomness()
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 . The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 ss obtained..**
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 s given. The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ..**.*/.typedef
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a fs sqlite3_vfs;.
90c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
90d0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
90e0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
90f0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
9100: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 sion number */.
9110: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
9120: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
9130: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
9140: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
9150: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
9160: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
9170: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
9180: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
9190: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
91a0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
91b0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
91c0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
91d0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
91e0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
91f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
9200: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
9210: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
9220: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
9230: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
9240: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
9250: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
9260: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
9270: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
9280: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
9290: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
92a0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
92b0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
92c0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
92d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
92e0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
92f0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
9300: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
9310: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
9320: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
9330: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
9340: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
9350: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f thname)(sqlite3_
9360: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
9370: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 *zName, int nOu
9380: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a t, char *zOut);.
9390: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 void *(*xDlOpe
93a0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
93b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
93c0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 lename);. void
93d0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 (*xDlError)(sqli
93e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
93f0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d yte, char *zErrM
9400: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a sg);. void (*(*
9410: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
9420: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
9430: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
9440: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 )(void);. void
9450: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 (*xDlClose)(sqli
9460: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 te3_vfs*, void*)
9470: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f ;. int (*xRando
9480: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 mness)(sqlite3_v
9490: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
94a0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 char *zOut);. i
94b0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c nt (*xSleep)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
94d0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 icroseconds);.
94e0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
94f0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
9500: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e , double*);. in
9510: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f t (*xGetLastErro
9520: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
9530: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 int, char *);.
9540: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d /* New fields m
9550: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
9560: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e n figure version
9570: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
9580: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
9590: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
95a0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
95b0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 . */.};../*.** C
95c0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
95d0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 or the xAccess V
95e0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
95f0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
9600: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 nstants can be u
9610: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
9620: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
9630: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
9640: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 hod of an [sqlit
9650: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 e3_vfs] object.
9660: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a They determine.
9670: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 ** what kind of
9680: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 permissions the
9690: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 xAccess method i
96a0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a s looking for..*
96b0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
96c0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 CESS_EXISTS, the
96d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
96e0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 ** simply checks
96f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
9700: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 e exists..** Wit
9710: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
9720: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 READWRITE, the x
9730: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
9740: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
9750: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 the file is both
9760: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
9770: 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 itable..** With
9780: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
9790: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 AD, the xAccess
97a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 method.** checks
97b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
97c0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a e is readable..*
97d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
97e0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 _ACCESS_EXISTS
97f0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
9800: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
9810: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ITE 1.#define SQ
9820: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
9830: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 2../*.** C
9840: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c API3REF: Initial
9850: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c ize The SQLite L
9860: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 ibrary.**.** ^Th
9870: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9880: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
9890: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
98a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
98b0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
98c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 shutdown() routi
98d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 ne.** deallocate
98e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 s any resources
98f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 that were alloca
9900: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
9910: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 nitialize()..**
9920: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
9930: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 re designed to a
9940: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e id in process in
9950: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
9960: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 .** shutdown on
9970: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 embedded systems
9980: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 . Workstation a
9990: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e pplications usin
99a0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d g.** SQLite norm
99b0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 ally do not need
99c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 to invoke eithe
99d0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 r of these routi
99e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c nes..**.** A cal
99f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 l to sqlite3_ini
9a00: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 tialize() is an
9a10: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
9a20: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 if it is.** the
9a30: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
9a40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9a50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 is invoked duri
9a60: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 ng the lifetime
9a70: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 of.** the proces
9a80: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 s, or if it is t
9a90: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
9aa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9ab0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
9ac0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
9ad0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
9ae0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 tdown(). ^(Only
9af0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
9b00: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
9b10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
9b20: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
9b30: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
9b40: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
9b50: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
9b60: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ^.**.** A call t
9b70: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
9b80: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 wn() is an "effe
9b90: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
9ba0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a t is the first.*
9bb0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
9bc0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 3_shutdown() sin
9bd0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 ce the last sqli
9be0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9bf0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 . ^(Only.** an
9c00: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
9c10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
9c20: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 wn() does any de
9c30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a initialization..
9c40: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c ** All other val
9c50: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 id calls to sqli
9c60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 te3_shutdown() a
9c70: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
9c80: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ps.)^.**.** The
9c90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9ca0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ze() interface i
9cb0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 s threadsafe, bu
9cc0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
9cd0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 wn().** is not.
9ce0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 The sqlite3_shu
9cf0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 tdown() interfac
9d00: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 e must only be c
9d10: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 alled from a.**
9d20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
9d30: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 All open [databa
9d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
9d50: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 must be closed a
9d60: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 nd all.** other
9d70: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 SQLite resources
9d80: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 must be dealloc
9d90: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e ated prior to in
9da0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 voking.** sqlite
9db0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 3_shutdown()..**
9dc0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 .** Among other
9dd0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 things, ^sqlite3
9de0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 _initialize() wi
9df0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ll invoke.** sql
9e00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
9e10: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c Similarly, ^sql
9e20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
9e30: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 ** will invoke s
9e40: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
9e50: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
9e60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9e70: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
9e80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
9e90: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 success..** ^If
9ea0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
9eb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9ec0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
9ed0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
9ee0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
9ef0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
9f00: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
9f10: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
9f20: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
9f30: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
9f40: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
9f50: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
9f60: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 TE_OK]..**.** ^T
9f70: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
9f80: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
9f90: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e is called intern
9fa0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 ally by many oth
9fb0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
9fc0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 erfaces so that
9fd0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 an application u
9fe0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 sually does not
9ff0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b need to.** invok
a000: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
a010: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e lize() directly.
a020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b For example, [
a030: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
a040: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 ** calls sqlite3
a050: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f _initialize() so
a060: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
a070: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ary will be auto
a080: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 matically.** ini
a090: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 tialized when [s
a0a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 qlite3_open()] i
a0b0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 s called if it h
a0c0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 as not be initia
a0d0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 lized.** already
a0e0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 . ^However, if
a0f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
a100: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
a110: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
a120: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
a130: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
a140: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
a150: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
a160: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
a170: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
a180: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
a190: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
a1a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
a1b0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
a1c0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
a1d0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a1e0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
a1f0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
a200: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
a210: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
a220: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
a230: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
a240: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
a250: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
a260: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
a270: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
a280: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
a290: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
a2a0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
a2b0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
a2c0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
a2d0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
a2e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
a2f0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
a300: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
a310: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
a320: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
a330: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
a340: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
a350: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
a360: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
a370: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
a380: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
a390: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
a3a0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
a3b0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
a3c0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
a3d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
a3e0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
a3f0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
a400: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
a410: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
a420: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
a430: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
a440: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
a450: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
a460: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
a470: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
a480: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
a490: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
a4a0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
a4b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
a4c0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
a4d0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
a4e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
a4f0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
a500: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
a510: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
a520: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
a530: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
a540: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
a550: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
a560: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
a570: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
a580: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
a590: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
a5a0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
a5b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
a5c0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
a5d0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
a5e0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
a5f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
a600: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a610: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
a620: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
a630: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
a640: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
a650: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
a660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
a670: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
a680: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
a690: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
a6a0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
a6b0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
a6c0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 piled for Unix,
a6d0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 Windows, or OS/2
a6e0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f ..** When [custo
a6f0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 m builds | built
a700: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 for other platf
a710: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 orms].** (using
a720: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
a730: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
a740: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
a750: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
a760: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
a770: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
a780: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
a790: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
a7a0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
a7b0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
a7c0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
a7d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a7e0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
a7f0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
a800: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
a810: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
a820: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
a830: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
a840: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
a850: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
a860: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
a870: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
a880: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a890: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
a8a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
a8b0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
a8c0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
a8d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a8e0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
a8f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
a900: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
a910: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
a920: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
a930: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
a940: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
a950: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
a960: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
a970: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
a980: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
a990: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
a9a0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
a9b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
a9c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
a9d0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
a9e0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
a9f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
aa00: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
aa10: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
aa20: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
aa30: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
aa40: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
aa50: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
aa60: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
aa70: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
aa80: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
aa90: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
aaa0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
aab0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
aac0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
aad0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
aae0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
aaf0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
ab00: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
ab10: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
ab20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ab30: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
ab40: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
ab50: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
ab60: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
ab70: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
ab80: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
ab90: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
aba0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
abb0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
abc0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
abd0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
abe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
abf0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
ac00: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
ac10: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
ac20: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
ac30: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
ac40: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
ac50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ac60: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
ac70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
ac80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
ac90: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
aca0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
acb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
acc0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
acd0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
ace0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
acf0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 n integer.** [SQ
ad00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
ad10: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
ad20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
ad30: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 that determines
ad40: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 .** what propert
ad50: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 y of SQLite is t
ad60: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e o be configured.
ad70: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 Subsequent arg
ad80: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 uments.** vary d
ad90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
ada0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
adb0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f INGLETHREAD | co
adc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
add0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
ade0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
adf0: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 .** ^When a conf
ae00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ae10: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 is set, sqlite3
ae20: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
ae30: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
ae40: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e * ^If the option
ae50: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 is unknown or S
ae60: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
ae70: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f to set the optio
ae80: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 n.** then this r
ae90: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
aea0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
aeb0: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 code]..*/.int s
aec0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e qlite3_config(in
aed0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t, ...);../*.**
aee0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
aef0: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ure database con
af00: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 nections.**.** T
af10: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
af20: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
af30: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
af40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
af50: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
af60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
af70: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
af80: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
af90: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
afa0: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
afb0: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
afc0: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
afd0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
afe0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
aff0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
b000: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 rst argument).
b010: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 The.** sqlite3_d
b020: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
b030: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 face should only
b040: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 be used immedia
b050: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 tely after.** th
b060: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
b070: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
b080: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
b090: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c open()],.** [sql
b0a0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
b0b0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
b0c0: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 _v2()]. .**.**
b0d0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
b0e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
b0f0: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
b100: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e ) is the.** con
b110: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 figuration verb
b120: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 - an integer cod
b130: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 e that indicates
b140: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 what.** aspect
b150: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
b160: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
b170: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
b180: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 ..** The only ch
b190: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 oice for this va
b1a0: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 lue is [SQLITE_D
b1b0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
b1c0: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 E]..** New verbs
b1d0: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 are likely to b
b1e0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
b1f0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
b200: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f Lite..** Additio
b210: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 nal arguments de
b220: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 pend on the verb
b230: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
b240: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
b250: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
b260: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
b270: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
b280: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
b290: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 successful..*/.i
b2a0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
b2b0: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
b2c0: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
b2d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
b2e0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
b2f0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
b300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
b310: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
b320: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
b330: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
b340: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
b350: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b360: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
b370: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
b380: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
b390: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
b3a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
b3b0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
b3c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
b3d0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
b3e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
b3f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
b400: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
b410: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
b420: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
b430: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
b440: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
b450: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
b460: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
b470: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
b480: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
b490: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
b4a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
b4b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
b4c0: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
b4d0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
b4e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
b4f0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
b500: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
b510: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b520: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
b530: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
b540: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
b550: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
b560: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
b570: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
b580: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
b590: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
b5a0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
b5b0: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
b5c0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
b5d0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
b5e0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
b5f0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
b600: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
b610: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
b620: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
b630: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
b640: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
b650: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
b660: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
b670: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
b680: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
b690: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
b6a0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
b6b0: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
b6c0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
b6d0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
b6e0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
b6f0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
b700: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
b710: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
b720: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
b730: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
b740: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
b750: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
b760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
b770: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 oc and xFree met
b780: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
b790: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
b7a0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
b7b0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
b7c0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
b7d0: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 rary..** The xRe
b7e0: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 alloc method mus
b7f0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c t work like real
b800: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 loc() from the s
b810: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
b820: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 y.** with the ex
b830: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 ception that if
b840: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
b850: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 ent to xRealloc
b860: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 is zero,.** xRea
b870: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e lloc must be a n
b880: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e o-op - it must n
b890: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 ot perform any a
b8a0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 llocation or.**
b8b0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e deallocation. ^
b8c0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
b8d0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
b8e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
b8f0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
b900: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
b910: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
b920: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
b930: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 ..** And so in c
b940: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e ases where xRoun
b950: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 dup always retur
b960: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 ns a positive nu
b970: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f mber,.** xReallo
b980: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 c can perform ex
b990: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 actly as the sta
b9a0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 ndard library re
b9b0: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 alloc() and.** s
b9c0: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c till be in compl
b9d0: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 iance with this
b9e0: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a specification..*
b9f0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
ba00: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
ba10: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
ba20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ba30: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
ba40: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
ba50: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
ba60: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
ba70: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
ba80: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
ba90: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
baa0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
bab0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
bac0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
bad0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
bae0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
baf0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
bb00: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
bb10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
bb20: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
bb30: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
bb40: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
bb50: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
bb60: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
bb70: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
bb80: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
bb90: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
bba0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
bbb0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
bbc0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
bbd0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
bbe0: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 * Every memory a
bbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
bc00: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f t coming in thro
bc10: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ugh [sqlite3_mal
bc20: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 loc()].** or [sq
bc30: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
bc40: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f first calls xRo
bc50: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e undup. If xRoun
bc60: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a dup returns 0, .
bc70: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 ** that causes t
bc80: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
bc90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
bca0: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a on to fail..**.*
bcb0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 * The xInit meth
bcc0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 od initializes t
bcd0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
bce0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 tor. (For examp
bcf0: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
bd00: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
bd10: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
bd20: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
bd30: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
bd40: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
bd50: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
bd60: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
bd70: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
bd80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
bd90: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
bda0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
bdb0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
bdc0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
bdd0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
bde0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
bdf0: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
be00: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
be10: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 Shutdown..**.**
be20: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 SQLite holds the
be30: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
be40: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 TATIC_MASTER] mu
be50: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f tex when it invo
be60: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 kes.** the xInit
be70: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 method, so the
be80: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 xInit method nee
be90: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 d not be threads
bea0: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 afe. The.** xSh
beb0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
bec0: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f only called fro
bed0: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 m [sqlite3_shutd
bee0: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 own()] so it doe
bef0: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f s.** not need to
bf00: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 be threadsafe e
bf10: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 ither. For all
bf20: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 other methods, S
bf30: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 QLite.** holds t
bf40: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
bf50: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 _STATIC_MEM] mut
bf60: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ex as long as th
bf70: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
bf80: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 FIG_MEMSTATUS] c
bf90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
bfa0: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e ion is turned on
bfb0: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 (which.** it is
bfc0: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 by default) and
bfd0: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 so the methods
bfe0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c are automaticall
bff0: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a y serialized..**
c000: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 However, if [SQ
c010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
c020: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c TATUS] is disabl
c030: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 ed, then the oth
c040: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 er.** methods mu
c050: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
c060: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 or else make th
c070: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d eir own arrangem
c080: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 ents for.** seri
c090: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a alization..**.**
c0a0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
c0b0: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
c0c0: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
c0d0: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
c0e0: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
c0f0: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
c100: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
c110: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
c120: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
c130: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
c140: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
c150: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
c160: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
c170: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
c180: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
c190: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
c1a0: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
c1b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
c1c0: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
c1d0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
c1e0: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
c1f0: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
c200: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
c210: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
c220: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
c230: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
c240: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
c250: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
c260: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
c270: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
c280: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
c290: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
c2a0: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
c2b0: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
c2c0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
c2d0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
c2e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
c2f0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
c300: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
c310: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
c320: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
c330: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
c340: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
c350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
c360: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
c370: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
c380: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
c390: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
c3a0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
c3b0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
c3c0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
c3d0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
c3e0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
c3f0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
c400: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
c410: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
c420: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
c430: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
c440: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
c450: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
c460: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
c470: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
c480: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
c490: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
c4a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
c4b0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
c4c0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
c4d0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
c4e0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
c4f0: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
c500: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
c510: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
c520: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
c530: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
c540: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
c550: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
c560: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
c570: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
c580: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
c590: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
c5a0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
c5b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
c5c0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
c5d0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
c5e0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
c5f0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
c600: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
c610: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
c620: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
c630: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
c640: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
c650: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
c660: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
c670: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
c680: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 .** all mutexing
c690: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 and puts SQLite
c6a0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 into a mode whe
c6b0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 re it can only b
c6c0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 e used.** by a s
c6d0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 ingle thread.
c6e0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
c6f0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
c700: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
c710: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
c720: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
c730: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
c740: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
c750: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 ot possible to c
c760: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 hange the [threa
c770: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 ding mode] from
c780: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 its default.** v
c790: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 alue of Single-t
c7a0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 hread and so [sq
c7b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
c7c0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 will return .**
c7d0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
c7e0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
c7f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
c800: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 SINGLETHREAD.**
c810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
c820: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
c830: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c840: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f IG_MULTITHREAD</
c850: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
c860: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
c870: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
c880: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
c890: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
c8a0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
c8b0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 Multi-thread. I
c8c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
c8d0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 t disables.** mu
c8e0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
c8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c900: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
c910: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
c920: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
c930: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
c940: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
c950: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
c960: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
c970: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
c980: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
c990: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
c9a0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
c9b0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
c9c0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
c9d0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
c9e0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
c9f0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
ca00: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
ca10: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
ca20: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
ca30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ca40: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
ca50: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c e time. ^If SQL
ca60: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
ca70: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
ca80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
ca90: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
caa0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
cab0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
cac0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
cad0: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 ible to set the
cae0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 Multi-thread [th
caf0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
cb00: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
cb10: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
cb20: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
cb30: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
cb40: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
cb50: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
cb60: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e AD configuration
cb70: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
cb80: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
cb90: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
cba0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
cbb0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
cbc0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
cbd0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
cbe0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
cbf0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
cc00: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e o Serialized. In
cc10: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
cc20: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
cc30: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
cc40: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
cc50: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
cc60: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
cc70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
cc80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
cc90: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
cca0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
ccb0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
ccc0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
ccd0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
cce0: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
ccf0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
cd00: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
cd10: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
cd20: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
cd30: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
cd40: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
cd50: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
cd60: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
cd70: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
cd80: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
cd90: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
cda0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
cdb0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
cdc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
cdd0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
cde0: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
cdf0: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 time..** ^If SQ
ce00: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
ce10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
ce20: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
ce30: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
ce40: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
ce50: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
ce60: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
ce70: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
ce80: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 Serialized [thr
ce90: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
cea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
ceb0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
cec0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
ced0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
cee0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
cef0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
cf00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
cf10: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
cf20: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
cf30: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
cf40: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
cf50: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
cf60: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
cf70: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
cf80: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
cf90: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
cfa0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
cfb0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
cfc0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
cfd0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
cfe0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
cff0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
d000: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
d010: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
d020: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
d030: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
d040: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
d050: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
d060: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
d070: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
d080: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
d090: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
d0a0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
d0b0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
d0c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
d0d0: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
d0e0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
d0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
d100: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
d110: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
d120: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
d130: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
d140: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
d150: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
d160: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
d170: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
d180: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c cture. The [sql
d190: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
d1a0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
d1b0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
d1c0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
d1d0: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
d1e0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 ation routines.)
d1f0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
d200: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
d210: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
d220: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
d230: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
d240: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
d250: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
d260: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
d270: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
d280: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
d290: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
d2a0: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ple. </dd>.**.**
d2b0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
d2c0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 IG_MEMSTATUS</dt
d2d0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
d2e0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e option takes sin
d2f0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
d300: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 type int, interp
d310: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 reted as a .** b
d320: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e oolean, which en
d330: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
d340: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e s the collection
d350: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 of memory alloc
d360: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 ation .** statis
d370: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d tics. ^(When mem
d380: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
d390: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 tatistics are di
d3a0: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 sabled, the .**
d3b0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 following SQLite
d3c0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f interfaces beco
d3d0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e me non-operation
d3e0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
d3f0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
d400: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
d410: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
d420: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
d430: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
d440: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
d450: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 eap_limit()].**
d460: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
d470: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c status()].** <
d480: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
d490: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
d4a0: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
d4b0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
d4c0: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
d4d0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
d4e0: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
d4f0: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
d500: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
d510: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
d520: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
d530: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
d540: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
d550: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d560: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
d570: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
d580: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
d590: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
d5a0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
d5b0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
d5c0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
d5d0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
d5e0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
d5f0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
d600: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
d610: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
d620: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
d630: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ach allocations
d640: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e will be.** drawn
d650: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
d660: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 ch scratch alloc
d670: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 ation (sz),.** a
d680: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e nd the maximum n
d690: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 umber of scratch
d6a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 allocations (N)
d6b0: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 . The sz.** arg
d6c0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
d6d0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 multiple of 16.
d6e0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 The sz parameter
d6f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 should be a few
d700: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 bytes.** larger
d710: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c than the actual
d720: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 scratch space r
d730: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 equired due to i
d740: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 nternal overhead
d750: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
d760: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
d770: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
d780: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
d790: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c uffer.** of at l
d7a0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
d7b0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
d7c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e QLite will use n
d7d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 o more than one
d7e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70 scratch buffer p
d7f0: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
d800: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
d810: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 t to the expecte
d820: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 d maximum number
d830: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 of threads. ^S
d840: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 QLite will.** ne
d850: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 ver require a sc
d860: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 ratch buffer tha
d870: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 t is more than 6
d880: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 times the datab
d890: 61 73 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 ase.** page size
d8a0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 . ^If SQLite nee
d8b0: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f ds needs additio
d8c0: 6e 61 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f nal scratch memo
d8d0: 72 79 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 ry beyond .** wh
d8e0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
d8f0: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 y this configura
d900: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 tion option, the
d910: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d n .** [sqlite3_m
d920: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 alloc()] will be
d930: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
d940: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 the memory neede
d950: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
d960: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
d970: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
d980: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
d990: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
d9a0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
d9b0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
d9c0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
d9d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
d9e0: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
d9f0: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
da00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f che implemenatio
da10: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e n. .** This con
da20: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c figuration shoul
da30: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 d not be used if
da40: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
da50: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 define page.** c
da60: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
da70: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 ion is loaded us
da80: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ing the SQLITE_C
da90: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 ONFIG_PCACHE opt
daa0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ion..** There ar
dab0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
dac0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
dad0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 : A pointer to 8
dae0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a -byte aligned.**
daf0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
db00: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
db10: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
db20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
db30: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
db40: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
db50: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
db60: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
db70: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
db80: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
db90: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 etween 512 and 3
dba0: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 2768) plus a lit
dbb0: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 tle extra for ea
dbc0: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 ch.** page heade
dbd0: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 r. ^The page he
dbe0: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 ader size is 20
dbf0: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 to 40 bytes depe
dc00: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 nding on.** the
dc10: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 host architectur
dc20: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c e. ^It is harml
dc30: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 ess, apart from
dc40: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 the wasted memor
dc50: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a y,.** to make sz
dc60: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 a little too la
dc70: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a rge. The first.
dc80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
dc90: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 ld point to an a
dca0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 llocation of at
dcb0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
dcc0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e of memory..** ^
dcd0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
dce0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 the memory provi
dcf0: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ded by the first
dd00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 argument to sat
dd10: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f isfy its.** memo
dd20: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 ry needs for the
dd30: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 first N pages t
dd40: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 hat it adds to c
dd50: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 ache. ^If addit
dd60: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
dd70: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
dd80: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
dd90: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
dda0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 this option, the
ddb0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 n.** SQLite goes
ddc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
ddd0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 loc()] for the a
dde0: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 dditional storag
ddf0: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 e space..** ^The
de00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
de10: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 might use one or
de20: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 more of the N b
de30: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a uffers to hold .
de40: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e ** memory accoun
de50: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ting information
de60: 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e . The pointer in
de70: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
de80: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 ent must.** be a
de90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
dea0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 yte boundary or
deb0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
dec0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ior of SQLite.**
ded0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
dee0: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
def0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
df00: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _HEAP</dt>.** <d
df10: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
df20: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
df30: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
df40: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
df50: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
df60: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
df70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
df80: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
df90: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
dfa0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
dfb0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
dfc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
dfd0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
dfe0: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
dff0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 e arguments: An
e000: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 8-byte aligned p
e010: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
e020: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d mory,.** the num
e030: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
e040: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
e050: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
e060: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
e070: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ze..** ^If the f
e080: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
e090: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
e0a0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 ) is NULL, then
e0b0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a SQLite reverts.*
e0c0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 * to using its d
e0d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
e0e0: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 locator (the sys
e0f0: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 tem malloc() imp
e100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a lementation),.**
e110: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 undoing any pri
e120: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 or invocation of
e130: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
e140: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 MALLOC]. ^If th
e150: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e e.** memory poin
e160: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ter is not NULL
e170: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 and either [SQLI
e180: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
e190: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 3] or.** [SQLITE
e1a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d _ENABLE_MEMSYS5]
e1b0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 are defined, th
e1c0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 en the alternati
e1d0: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c ve memory.** all
e1e0: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 ocator is engage
e1f0: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 d to handle all
e200: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 of SQLites memor
e210: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
e220: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ds..** The first
e230: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
e240: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 mory pointer) mu
e250: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
e260: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f an 8-byte.** bo
e270: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 undary or subseq
e280: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 uent behavior of
e290: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
e2a0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a undefined.</dd>.
e2b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e2c0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 _CONFIG_MUTEX</d
e2d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
e2e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
e2f0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
e300: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
e310: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
e320: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
e330: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
e340: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
e350: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
e360: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
e370: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
e380: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
e390: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c to be used in pl
e3a0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 ace.** the mutex
e3b0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
e3c0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 into SQLite.)^
e3d0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 ^SQLite makes a
e3e0: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 copy of the.** c
e3f0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
e400: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
e410: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 hods] structure
e420: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 before the call
e430: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
e440: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 onfig()] returns
e450: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 . ^If SQLite is
e460: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
e470: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
e480: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
e490: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
e4a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
e4b0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
e4c0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
e4d0: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
e4e0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
e4f0: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
e500: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
e510: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
e520: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
e530: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 IG_MUTEX configu
e540: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
e550: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
e560: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
e570: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
e580: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
e590: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
e5a0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
e5b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
e5c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
e5d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
e5e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
e5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
e600: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
e610: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ure. The.** [sq
e620: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
e630: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
e640: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
e650: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
e660: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 efined mutex rou
e670: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 tines.)^.** This
e680: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
e690: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
e6a0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
e6b0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
e6c0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
e6d0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
e6e0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
e6f0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
e700: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
e710: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
e720: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 xample. ^If SQ
e730: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
e740: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
e750: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
e760: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
e770: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
e780: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
e790: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
e7a0: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
e7b0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
e7c0: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
e7d0: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
e7e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
e7f0: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
e800: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
e810: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f TEX configuratio
e820: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a n option will.**
e830: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
e840: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a ERROR].</dd>.**.
e850: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
e860: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
e870: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
e880: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
e890: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 two arguments th
e8a0: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
e8b0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f default.** memo
e8c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f ry allocation fo
e8d0: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 r the lookaside
e8e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
e8f0: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 on each.** [dat
e900: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e910: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 ]. The first ar
e920: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
e930: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
e940: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
e950: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f lot and the seco
e960: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nd is the number
e970: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c of.** slots all
e980: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 ocated to each d
e990: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e9a0: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 on.)^ ^(This op
e9b0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
e9c0: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 <i>default</i>
e9d0: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 lookaside size.
e9e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f The [SQLITE_DBCO
e9f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a NFIG_LOOKASIDE].
ea00: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 ** verb to [sqli
ea10: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
ea20: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
ea30: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 change the looka
ea40: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 side.** configur
ea50: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 ation on individ
ea60: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e ual connections.
ea70: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c )^ </dd>.**.** <
ea80: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
ea90: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 _PCACHE</dt>.**
eaa0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
eab0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
eac0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
ead0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
eae0: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f .** an [sqlite3_
eaf0: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 pcache_methods]
eb00: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 object. This ob
eb10: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 ject specifies t
eb20: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
eb30: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 to a custom page
eb40: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
eb50: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 ation.)^ ^SQLit
eb60: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
eb70: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 f the.** object
eb80: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 and uses it for
eb90: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
eba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f y allocations.</
ebb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
ebc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
ebd0: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
ebe0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
ebf0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
ec00: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
ec10: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
ec20: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 n.** [sqlite3_pc
ec30: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 ache_methods] ob
ec40: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
ec50: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 pies of the curr
ec60: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 ent.** page cach
ec70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
ec80: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
ec90: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
eca0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
ecb0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
ecc0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
ecd0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
ece0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
ecf0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
ed00: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
ed10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
ed20: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
ed30: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#de
ed40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ed50: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
ed60: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* sqlite3_m
ed70: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
ed80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ed90: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
eda0: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
edb0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
edc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
edd0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
ede0: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 6 /* void*
edf0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
ee00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ee10: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
ee20: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 HE 7 /* voi
ee30: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
ee40: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
ee50: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
ee60: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 8 /* v
ee70: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c oid*, int nByte,
ee80: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 int min */.#def
ee90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
eea0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 G_MEMSTATUS
eeb0: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 9 /* boolean */
eec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
eed0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 CONFIG_MUTEX
eee0: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 10 /* sqlit
eef0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
ef00: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
ef10: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
ef20: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 TEX 11 /* s
ef30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
ef40: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 hods* */./* prev
ef50: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f iously SQLITE_CO
ef60: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
ef70: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 12 which is now
ef80: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 unused. */ .#def
ef90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
efa0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 G_LOOKASIDE 1
efb0: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 3 /* int int */
efc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
efd0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 CONFIG_PCACHE
efe0: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 14 /* sqlit
eff0: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
f000: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
f010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
f020: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
f030: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
f040: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
f050: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
f060: 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 _LOG 16
f070: 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 /* xFunc, void
f080: 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 * */../*.** CAPI
f090: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
f0a0: 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 onnection Config
f0b0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
f0c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
f0d0: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
f0e0: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
f0f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
f100: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
f110: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
f120: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
f130: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
f140: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
f150: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
f160: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
f170: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
f180: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
f190: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
f1a0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
f1b0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
f1c0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
f1d0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
f1e0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
f1f0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
f200: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
f210: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
f220: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
f230: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
f240: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
f250: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
f260: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
f270: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
f280: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
f290: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
f2a0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
f2b0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
f2c0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f2d0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
f2e0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
f2f0: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
f300: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
f310: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
f320: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
f330: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
f340: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
f350: 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
f360: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
f370: 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
f380: 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
f390: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
f3a0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
f3b0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
f3c0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
f3d0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
f3e0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
f3f0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
f400: 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 an memory buffer
f410: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
f420: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a aside memory..**
f430: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
f440: 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 ment after the S
f450: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
f460: 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a OOKASIDE verb.**
f470: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
f480: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
f490: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
f4a0: 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
f4b0: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
f4c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
f4d0: 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 lloc()]. ^The se
f4e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
f4f0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
f500: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
f510: 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 uffer slot. ^Th
f520: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
f530: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
f540: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
f550: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
f560: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
f570: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
f580: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
f590: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
f5a0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
f5b0: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
f5c0: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 d arguments. Th
f5d0: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 e buffer.** must
f5e0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
f5f0: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
f600: 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f y. ^If the seco
f610: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
f620: 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 * SQLITE_DBCONFI
f630: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e G_LOOKASIDE is n
f640: 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ot a multiple of
f650: 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 8, it is intern
f660: 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 ally.** rounded
f670: 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
f680: 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 smaller.** mult
f690: 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 iple of 8. See
f6a0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f also: [SQLITE_CO
f6b0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c NFIG_LOOKASIDE]<
f6c0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
f6d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f6e0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
f6f0: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
f700: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
f710: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
f720: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
f730: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
f740: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a Result Codes.**.
f750: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f760: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
f770: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 codes() routine
f780: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
f790: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 les the.** [exte
f7a0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
f7b0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 s] feature of SQ
f7c0: 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e Lite. ^The exten
f7d0: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
f7e0: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
f7f0: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
f800: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
f810: 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 tibility..*/.int
f820: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
f830: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 d_result_codes(s
f840: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f qlite3*, int ono
f850: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
f860: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 3REF: Last Inser
f870: 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 t Rowid.**.** ^E
f880: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 ach entry in an
f890: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 SQLite table has
f8a0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
f8b0: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 signed.** integ
f8c0: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 er key called th
f8d0: 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 e [ROWID | "rowi
f8e0: 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 d"]. ^The rowid
f8f0: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
f900: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
f910: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
f920: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
f930: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
f940: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
f950: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
f960: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
f970: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
f980: 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 olumns. ^If.** t
f990: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 he table has a c
f9a0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 olumn of type [I
f9b0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
f9c0: 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f EY] then that co
f9d0: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 lumn.** is anoth
f9e0: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 er alias for the
f9f0: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rowid..**.** ^T
fa00: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
fa10: 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
fa20: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 of the most rece
fa30: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c nt.** successful
fa40: 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 [INSERT] into t
fa50: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
fa60: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
fa70: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e onnection].** in
fa80: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
fa90: 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 ent. ^If no suc
faa0: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
fab0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
fac0: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
fad0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
fae0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
faf0: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 urned..**.** ^(I
fb00: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
fb10: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
fb20: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 igger, then the
fb30: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
fb40: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 nserted.** row i
fb50: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
fb60: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f is routine as lo
fb70: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
fb80: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a r is running..**
fb90: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
fba0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 igger terminates
fbb0: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
fbc0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
fbd0: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 tine.** reverts
fbe0: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 to the last valu
fbf0: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 e inserted befor
fc00: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 e the trigger fi
fc10: 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e red.)^.**.** ^An
fc20: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
fc30: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
fc40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
fc50: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
fc60: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
fc70: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
fc80: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
fc90: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
fca0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
fcb0: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
fcc0: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
fcd0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
fce0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
fcf0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
fd00: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
fd10: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
fd20: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
fd30: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
fd40: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
fd50: 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
fd60: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
fd70: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
fd80: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
fd90: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
fda0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
fdb0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
fdc0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
fdd0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
fde0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
fdf0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
fe00: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
fe10: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
fe20: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
fe30: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
fe40: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
fe50: 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
fe60: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
fe70: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
fe80: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
fe90: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
fea0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
feb0: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
fec0: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
fed0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
fee0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
fef0: 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
ff00: 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
ff10: 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
ff20: 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
ff30: 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
ff40: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
ff50: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
ff60: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
ff70: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
ff80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ff90: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
ffa0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
ffb0: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
ffc0: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
ffd0: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
ffe0: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
fff0: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
10000 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
10010 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
10020 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
10030 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
10040 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
10050 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
10060 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
10070 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
10080 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
10090 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
100a0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
100b0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
100c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
100d0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
100e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
100f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
10100 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
10110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
10120 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
10130 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
10140 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 ged.** or insert
10150 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 ed or deleted by
10160 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
10170 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c ly completed SQL
10180 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e statement.** on
10190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
101a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
101b0 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
101c0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
101d0 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 ^(Only changes t
101e0 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
101f0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
10200 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
10210 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
10220 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
10230 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
10240 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
10250 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
10260 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e gers or [foreign
10270 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 key actions] ar
10280 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e e not counted.)^
10290 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c Use the.** [sql
102a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
102b0 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 es()] function t
102c0 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c o find the total
102d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
102e0 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 es.** including
102f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
10300 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 y triggers and f
10310 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
10320 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 ns..**.** ^Chang
10330 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
10340 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 t are simulated
10350 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f by an [INSTEAD O
10360 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 F trigger].** ar
10370 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 e not counted.
10380 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 Only real table
10390 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
103a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 ted..**.** ^(A "
103b0 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
103c0 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
103d0 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
103e0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
103f0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
10400 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
10410 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
10420 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
10430 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
10440 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 effects of [REP
10450 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 LACE] constraint
10460 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 resolution,.**
10470 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 rollback, ABORT
10480 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f processing, [DRO
10490 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 P TABLE], or by
104a0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 any other.** mec
104b0 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 hanisms do not c
104c0 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 ount as direct r
104d0 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a ow changes.)^.**
104e0 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 .** A "trigger c
104f0 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f ontext" is a sco
10500 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 pe of execution
10510 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a that begins and.
10520 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 ** ends with the
10530 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 script of a [CR
10540 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
10550 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 rigger]. .** Mos
10560 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
10570 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 are.** evaluate
10580 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 d outside of any
10590 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 trigger. This
105a0 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 is the "top leve
105b0 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f l".** trigger co
105c0 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 ntext. If a tri
105d0 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 gger fires from
105e0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 the top level, a
105f0 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 .** new trigger
10600 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 context is enter
10610 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 ed for the durat
10620 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a ion of that one.
10630 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 ** trigger. Sub
10640 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 triggers create
10650 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 subcontexts for
10660 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a their duration..
10670 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b **.** ^Calling [
10680 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
10690 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
106a0 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
106b0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
106c0 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
106d0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
106e0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
106f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
10700 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 r of direct row
10710 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a changes in the.*
10720 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e * most recent IN
10730 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
10740 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
10750 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
10760 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e e.** trigger con
10770 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 text..**.** ^Thu
10780 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 s, when called f
10790 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
107a0 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e l, this function
107b0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
107c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
107d0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
107e0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
107f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
10800 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 * that also occu
10810 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 rred at the top
10820 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e level. ^(Within
10830 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 the body of a t
10840 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 rigger,.** the s
10850 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
10860 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
10870 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 e called to find
10880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
10890 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 * changes in the
108a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
108b0 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
108c0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
108d0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
108e0 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 within the body
108f0 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 of the same trig
10900 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ger..** However,
10910 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 the number retu
10920 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
10930 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a clude changes.**
10940 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 caused by subtr
10950 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f iggers since tho
10960 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 se have their ow
10970 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a n context.)^.**.
10980 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
10990 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
109a0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
109b0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 ace, the.** [cou
109c0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
109d0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 a], and the [cha
109e0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
109f0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
10a00 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
10a10 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
10a20 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
10a30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
10a40 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 * while [sqlite3
10a50 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 _changes()] is r
10a60 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 unning then the
10a70 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
10a80 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 * is unpredictab
10a90 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
10aa0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
10ab0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 lite3_changes(sq
10ac0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
10ad0 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 CAPI3REF: Total
10ae0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
10af0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 odified.**.** ^T
10b00 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
10b10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
10b20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
10b30 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 aused by [INSERT
10b40 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f ],.** [UPDATE] o
10b50 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
10b60 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
10b70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10b80 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
10b90 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 ..** ^(The count
10ba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
10bb0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
10bc0 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c es() includes al
10bd0 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f l changes.** fro
10be0 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 m all [CREATE TR
10bf0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d IGGER | trigger]
10c00 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 contexts and ch
10c10 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a anges made by.**
10c20 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
10c30 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c tions]. However,
10c40 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f .** the count do
10c50 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
10c60 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 hanges used to i
10c70 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 mplement [REPLAC
10c80 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a E] constraints,.
10c90 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 ** do rollbacks
10ca0 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 or ABORT process
10cb0 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 ing, or [DROP TA
10cc0 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e BLE] processing.
10cd0 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 The.** count d
10ce0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
10cf0 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 rows of views th
10d00 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 at fire an [INST
10d10 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c EAD OF trigger],
10d20 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 .** though if th
10d30 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 e INSTEAD OF tri
10d40 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 gger makes chang
10d50 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 es of its own, t
10d60 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a hose changes .**
10d70 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a are counted.)^.
10d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
10d90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
10da0 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 function counts
10db0 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 the changes as s
10dc0 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 oon as.** the st
10dd0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b atement that mak
10de0 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c es them is compl
10df0 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 eted (when the s
10e00 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a tatement handle.
10e10 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 ** is passed to
10e20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
10e30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
10e40 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a nalize()])..**.*
10e50 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
10e60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
10e70 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 )] interface, th
10e80 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e e.** [count_chan
10e90 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 ges pragma], and
10ea0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e the [total_chan
10eb0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
10ec0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
10ed0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
10ee0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
10ef0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
10f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
10f10 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
10f20 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
10f30 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
10f40 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
10f50 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
10f60 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
10f70 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
10f80 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c nt sqlite3_total
10f90 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
10fa0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
10fb0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
10fc0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
10fd0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ery.**.** ^This
10fe0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
10ff0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
11000 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
11010 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
11020 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
11030 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
11040 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
11050 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
11060 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
11070 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
11080 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
11090 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
110a0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
110b0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
110c0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
110d0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
110e0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
110f0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
11100 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
11110 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
11120 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
11130 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
11140 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
11150 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
11160 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
11170 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
11180 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
11190 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
111a0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
111b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
111c0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
111d0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
111e0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
111f0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
11200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
11210 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
11220 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
11230 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
11240 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
11250 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
11260 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
11270 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
11280 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
11290 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
112a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
112b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
112c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
112d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
112e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
112f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
11300 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
11310 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
11320 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
11330 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
11340 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
11350 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
11360 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
11370 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
11380 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
11390 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
113a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
113b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
113c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
113d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
113e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
113f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
11400 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
11410 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
11420 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
11430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
11440 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
11450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
11460 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
11470 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
11480 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
11490 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
114a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
114b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
114c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
114d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
114e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
114f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
11500 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
11510 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
11520 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
11530 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
11540 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
11550 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
11560 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
11570 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
11580 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
11590 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
115a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
115b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
115c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
115d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
115e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
115f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
11600 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
11610 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
11620 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
11630 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
11640 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
11650 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
11660 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
11670 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
11680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11690 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
116a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
116b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
116c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
116d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
116e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 happen..*/.void
116f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
11700 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
11710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
11720 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
11730 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
11740 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 omplete.**.** Th
11750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
11760 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
11770 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
11780 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
11790 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
117a0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
117b0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
117c0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
117d0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
117e0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
117f0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
11800 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
11810 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
11820 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
11830 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
11840 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 return 1 if the
11850 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
11860 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
11870 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
11880 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 tement. ^A stat
11890 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
118a0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
118b0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
118c0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
118d0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
118e0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 prefix of a.**
118f0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 well-formed CREA
11900 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
11910 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f ment. ^Semicolo
11920 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
11930 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
11940 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
11950 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
11960 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
11970 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
11980 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
11990 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
119a0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
119b0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
119c0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
119d0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
119e0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
119f0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ent terminator.
11a00 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 ^Whitespace.**
11a10 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 and comments tha
11a20 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e t follow the fin
11a30 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 al semicolon are
11a40 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
11a50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
11a60 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 return 0 if the
11a70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 statement is inc
11a80 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a omplete. ^If a.
11a90 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
11aa0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e tion fails, then
11ab0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 SQLITE_NOMEM is
11ac0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
11ad0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
11ae0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 do not parse th
11af0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
11b00 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f thus.** will no
11b10 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 t detect syntact
11b20 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 ically incorrect
11b30 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 SQL..**.** ^(If
11b40 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 SQLite has not
11b50 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 been initialized
11b60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
11b70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 initialize()] pr
11b80 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b ior .** to invok
11b90 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ing sqlite3_comp
11ba0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 lete16() then sq
11bb0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11bc0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
11bd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
11be0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 y sqlite3_comple
11bf0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 te16(). If that
11c00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
11c10 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 fails,.** then t
11c20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
11c30 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d from sqlite3_com
11c40 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 plete16() will b
11c50 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 e non-zero.** re
11c60 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
11c70 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 her or not the i
11c80 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 nput SQL is comp
11c90 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 lete.)^.**.** Th
11ca0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
11cb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 te3_complete()]
11cc0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
11cd0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
11ce0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a -8 string..**.**
11cf0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
11d00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
11d10 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
11d20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
11d30 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 * UTF-16 string
11d40 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
11d50 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
11d60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
11d70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
11d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
11d90 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
11da0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
11db0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
11dc0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
11dd0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
11de0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a USY Errors.**.**
11df0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^This routine s
11e00 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
11e10 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 unction that mig
11e20 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 ht be invoked wh
11e30 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
11e40 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
11e50 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 open a database
11e60 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 table that anoth
11e70 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 er thread.** or
11e80 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b process has lock
11e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
11ea0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
11eb0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
11ec0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
11ed0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
11ee0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 CKED].** is retu
11ef0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
11f00 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 upon encounteri
11f10 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 ng the lock. ^I
11f20 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
11f30 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 ack.** is not NU
11f40 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c LL, then the cal
11f50 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 lback might be i
11f60 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 nvoked with two
11f70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
11f80 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
11f90 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 ment to the busy
11fa0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
11fb0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
11fc0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
11fd0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
11fe0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
11ff0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
12000 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 . ^The second a
12010 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
12020 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 e busy handler c
12030 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
12040 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
12050 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e hat the busy han
12060 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e dler has.** been
12070 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 invoked for thi
12080 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e s locking event.
12090 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
120a0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
120b0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
120c0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
120d0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
120e0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
120f0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
12100 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
12110 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
12120 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
12130 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
12140 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
12150 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
12160 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
12170 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 ade to open the
12180 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 database for rea
12190 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 ding and the cyc
121a0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
121b0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
121c0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
121d0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
121e0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
121f0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
12200 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
12210 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 k contention. ^I
12220 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
12230 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
12240 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
12250 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
12260 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
12270 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
12280 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
12290 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f QLITE_BUSY].** o
122a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
122b0 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 BLOCKED] instead
122c0 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
122d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
122e0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
122f0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
12300 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
12310 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
12320 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
12330 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
12340 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
12350 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
12360 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
12370 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
12380 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
12390 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
123a0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
123b0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
123c0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
123d0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
123e0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
123f0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
12400 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
12410 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
12420 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
12430 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
12440 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
12450 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
12460 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
12470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
12480 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
12490 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
124a0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
124b0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
124c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
124d0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
124e0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
124f0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
12500 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
12510 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
12520 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
12530 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
12540 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
12550 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
12560 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 ^The default bu
12570 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
12580 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ULL..**.** ^The
12590 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 [SQLITE_BUSY] er
125a0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 ror is converted
125b0 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 to [SQLITE_IOER
125c0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 R_BLOCKED].** wh
125d0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 en SQLite is in
125e0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 the middle of a
125f0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f large transactio
12600 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a n where all the.
12610 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ** changes will
12620 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 not fit into the
12630 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 in-memory cache
12640 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a . SQLite will.*
12650 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 * already hold a
12660 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f RESERVED lock o
12670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
12680 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 ile, but it need
12690 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 s.** to promote
126a0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 this lock to EXC
126b0 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 LUSIVE so that i
126c0 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 t can spill cach
126d0 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 e.** pages into
126e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
126f0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 e without harm t
12700 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 o concurrent.**
12710 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 readers. ^If it
12720 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 is unable to pr
12730 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 omote the lock,
12740 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f then the in-memo
12750 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c ry.** cache will
12760 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 be left in an i
12770 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 nconsistent stat
12780 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 e and so the err
12790 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 or.** code is pr
127a0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 omoted from the
127b0 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 relatively benig
127c0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
127d0 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 to.** the more s
127e0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f evere [SQLITE_IO
127f0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e ERR_BLOCKED]. ^
12800 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 This error code
12810 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 promotion.** for
12820 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 ces an automatic
12830 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 rollback of the
12840 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 changes. See t
12850 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f he.** <a href="/
12860 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 cvstrac/wiki?p=C
12870 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
12880 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a ngBusyError">.**
12890 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f CorruptionFollo
128a0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 wingBusyError</a
128b0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 > wiki page for
128c0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 a discussion of
128d0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 why.** this is i
128e0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 mportant..**.**
128f0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
12900 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
12910 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
12920 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
12930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12940 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
12950 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
12960 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
12970 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
12980 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 ndler.)^ ^Note
12990 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
129a0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
129b0 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c ut()].** will al
129c0 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 so set or clear
129d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
129e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
129f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
12a00 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
12a10 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
12a20 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
12a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
12a40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
12a50 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e usy handler. An
12a60 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
12a70 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
12a80 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
12a90 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 ** .** A busy ha
12aa0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 ndler must not c
12ab0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
12ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
12ad0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 or [prepared sta
12ae0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 tement] that inv
12af0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
12b00 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndler..*/.int sq
12b10 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
12b20 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
12b30 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
12b40 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
12b50 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
12b60 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
12b70 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
12b80 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
12b90 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
12ba0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
12bb0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
12bc0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
12bd0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
12be0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
12bf0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
12c00 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
12c10 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
12c20 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
12c30 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
12c40 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
12c50 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
12c60 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
12c70 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
12c80 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
12c90 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
12ca0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
12cb0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
12cc0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
12cd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
12ce0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
12cf0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
12d00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
12d10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
12d20 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
12d30 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
12d40 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
12d50 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
12d60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
12d70 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
12d80 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
12d90 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
12da0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
12db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
12dc0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
12dd0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
12de0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
12df0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
12e00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
12e10 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
12e20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
12e30 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
12e40 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
12e50 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
12e60 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 red.)^.*/.int sq
12e70 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
12e80 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
12e90 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
12ea0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
12eb0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
12ec0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
12ed0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e **.** Definition
12ee0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 : A <b>result ta
12ef0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 ble</b> is memor
12f00 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 y data structure
12f10 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a created by the.
12f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
12f30 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 table()] interfa
12f40 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 ce. A result ta
12f50 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a ble records the.
12f60 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 ** complete quer
12f70 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f y results from o
12f80 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 ne or more queri
12f90 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 es..**.** The ta
12fa0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 ble conceptually
12fb0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 has a number of
12fc0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e rows and column
12fd0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 s. But.** these
12fe0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 numbers are not
12ff0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 part of the res
13000 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 ult table itself
13010 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 . These.** numb
13020 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 ers are obtained
13030 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 separately. Le
13040 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 t N be the numbe
13050 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 r of rows.** and
13060 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 M be the number
13070 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a of columns..**.
13080 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
13090 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 e is an array of
130a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
130b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
130c0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 -8 strings..** T
130d0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d here are (N+1)*M
130e0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 elements in the
130f0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 array. The fir
13100 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f st M pointers po
13110 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 int.** to zero-t
13120 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
13130 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 s that contain
13140 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
13150 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 columns..** The
13160 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 remaining entri
13170 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 es all point to
13180 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 query results.
13190 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 NULL values resu
131a0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f lt.** in NULL po
131b0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 inters. All oth
131c0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e er values are in
131d0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 their UTF-8 zer
131e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
131f0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
13200 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 ation as returne
13210 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
13220 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
13230 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
13240 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 le might consist
13250 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
13260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
13270 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 ns..** It is not
13280 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 safe to pass a
13290 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 result table dir
132a0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 ectly to [sqlite
132b0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 3_free()]..** A
132c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f result table sho
132d0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 uld be deallocat
132e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
132f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
13300 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 .**.** As an exa
13310 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
13320 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
13330 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
13340 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
13350 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
13360 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
13370 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
13380 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
13390 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
133a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
133b0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
133c0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
133d0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
133e0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
133f0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
13400 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
13410 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
13420 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
13430 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
13440 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
13450 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
13460 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
13470 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
13480 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
13490 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
134a0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
134b0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
134c0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
134d0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
134e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
134f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
13500 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
13510 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
13520 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
13530 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
13540 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
13550 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
13560 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
13570 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
13580 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
13590 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
135a0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
135b0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
135c0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
135d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
135e0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
135f0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
13600 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
13610 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
13620 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e ckquote>.**.** ^
13630 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
13640 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
13650 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
13660 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
13670 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
13680 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
13690 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
136a0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
136b0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
136c0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
136d0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
136e0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
136f0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
13700 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
13710 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
13720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 e application ha
13730 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
13740 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 the result from
13750 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
13760 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c e(),.** it shoul
13770 64 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c d pass the resul
13780 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
13790 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
137a0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
137b0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
137c0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
137d0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
137e0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
137f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
13800 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
13810 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
13820 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
13830 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
13840 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
13850 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
13860 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
13870 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
13880 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
13890 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
138a0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
138b0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
138c0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
138d0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^(The sqlite3_ge
138e0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 t_table() interf
138f0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ace is implement
13900 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 ed as a wrapper
13910 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
13920 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 e3_exec()]. The
13930 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
13940 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 le() routine doe
13950 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 s not have acces
13960 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 s.** to any inte
13970 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 rnal data struct
13980 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ures of SQLite.
13990 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 It uses only th
139a0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 e public.** inte
139b0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 rface defined he
139c0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 re. As a conseq
139d0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 uence, errors th
139e0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a at occur in the.
139f0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 ** wrapper layer
13a00 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
13a10 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 internal [sqlite
13a20 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 3_exec()] call a
13a30 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 re not.** reflec
13a40 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e ted in subsequen
13a50 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
13a60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f te3_errcode()] o
13a70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 r.** [sqlite3_er
13a80 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e rmsg()].)^.*/.in
13a90 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
13aa0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
13ab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
13ac0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
13ad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
13ae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
13af0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
13b00 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
13b10 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
13b20 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
13b30 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
13b40 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
13b50 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
13b60 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
13b70 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
13b80 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
13b90 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
13ba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
13bb0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
13bc0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
13bd0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
13be0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
13bf0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
13c00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
13c10 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
13c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
13c30 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
13c40 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
13c50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
13c60 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
13c70 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
13c80 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
13c90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
13ca0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
13cb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
13cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
13cd0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
13ce0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
13cf0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
13d00 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
13d10 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
13d20 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
13d30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
13d40 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
13d50 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
13d60 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
13d70 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
13d80 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
13d90 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
13da0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
13db0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
13dc0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
13dd0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
13de0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
13df0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
13e00 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
13e10 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
13e20 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f ** ^(In sqlite3_
13e30 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
13e40 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
13e50 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
13e60 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
13e70 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
13e80 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
13e90 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
13ea0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
13eb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
13ec0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
13ed0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
13ee0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
13ef0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
13f00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
13f10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
13f20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
13f30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
13f40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
13f50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
13f60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
13f70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
13f80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
13f90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
13fa0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
13fb0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
13fc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
13fd0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
13fe0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
13ff0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
14000 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
14010 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
14020 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
14030 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
14040 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
14050 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
14060 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
14070 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
14080 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
14090 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
140a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
140b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
140c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
140d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
140e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
140f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
14100 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
14110 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
14120 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
14130 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
14140 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
14150 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
14160 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
14170 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
14180 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
14190 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
141a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
141b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
141c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
141d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
141e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
141f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
14200 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
14210 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
14220 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
14230 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
14240 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
14250 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
14260 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
14270 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
14280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
14290 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
142a0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
142b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
142c0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
142d0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
142e0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
142f0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
14300 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
14310 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
14320 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
14330 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
14340 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
14350 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
14360 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 titutes a null-t
14370 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
14380 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 ing from the arg
14390 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 ument list. But
143a0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 %q also doubles
143b0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 every '\'' char
143c0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 acter..** %q is
143d0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 designed for use
143e0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 inside a string
143f0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 literal.)^ By
14400 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
14410 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
14420 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
14430 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
14440 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
14450 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
14460 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
14470 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
14480 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
14490 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
144a0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
144b0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
144c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
144d0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
144e0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
144f0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
14500 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
14510 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
14520 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
14530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
14540 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
14550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
14560 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
14570 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
14580 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
14590 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
145a0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
145b0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
145c0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
145d0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
145e0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
145f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
14600 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
14610 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
14620 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
14630 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
14640 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
14650 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
14660 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
14670 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
14680 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
14690 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
146a0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
146b0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
146c0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
146d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
146e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
146f0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
14700 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
14710 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
14720 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
14730 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
14740 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
14750 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
14760 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
14770 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
14780 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
14790 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
147a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
147b0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
147c0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
147d0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
147e0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
147f0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
14800 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
14810 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
14820 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
14830 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
14840 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ral..**.** ^(The
14850 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
14860 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
14870 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
14880 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
14890 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
148a0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
148b0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
148c0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
148d0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
148e0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
148f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
14900 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
14910 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
14920 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
14930 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 le quotes).)^ S
14940 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 o, for example,
14950 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a one could say:.*
14960 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
14970 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
14980 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
14990 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
149a0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
149b0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a S(%Q)", zText);.
149c0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
149d0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
149e0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
149f0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
14a00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
14a10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f te>.**.** The co
14a20 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 de above will re
14a30 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 nder a correct S
14a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
14a50 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 the zSQL.** vari
14a60 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 able even if the
14a70 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 zText variable
14a80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
14a90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 r..**.** ^(The "
14aa0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
14ab0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
14ac0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
14ad0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
14ae0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
14af0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
14b00 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
14b10 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
14b20 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
14b30 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
14b40 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
14b50 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c .)^.*/.char *sql
14b60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
14b70 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
14b80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
14b90 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
14ba0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
14bb0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
14bc0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
14bd0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
14be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14bf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
14c00 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
14c10 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
14c20 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
14c30 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
14c40 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
14c50 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
14c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
14c70 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
14c80 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
14c90 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
14ca0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
14cb0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
14cc0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
14cd0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
14ce0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
14cf0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
14d00 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
14d10 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
14d20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
14d30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
14d40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
14d50 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
14d60 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
14d70 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
14d80 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
14d90 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
14da0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
14db0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
14dc0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
14dd0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
14de0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
14df0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
14e00 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
14e10 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
14e20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
14e30 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
14e40 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
14e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
14e60 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
14e70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ointer..**.** ^C
14e80 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
14e90 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
14ea0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
14eb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
14ec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
14ed0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
14ee0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
14ef0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
14f00 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
14f10 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 reused. ^The s
14f20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
14f30 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
14f40 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
14f50 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
14f60 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
14f70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
14f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
14f90 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
14fa0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
14fb0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
14fc0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
14fd0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
14fe0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
14ff0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
15000 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
15010 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
15020 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
15030 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
15040 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
15050 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
15060 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
15070 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
15080 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
15090 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
150a0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
150b0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
150c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
150d0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
150e0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
150f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
15100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15110 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
15120 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
15130 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
15140 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
15150 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
15160 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
15170 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
15180 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
15190 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
151a0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
151b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
151c0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
151d0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
151e0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 eter.)^ ^ If the
151f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
15200 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
15210 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
15220 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
15230 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
15240 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
15250 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
15260 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
15270 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
15280 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
15290 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
152a0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e ** ^If the secon
152b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
152c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
152d0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
152e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
152f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
15300 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
15310 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
15320 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 te3_free(P) wher
15330 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 e P is the first
15340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
15350 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
15360 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
15370 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
15380 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
15390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
153a0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
153b0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
153c0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
153d0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
153e0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e navailable..** ^
153f0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 If M is the size
15400 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
15410 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d location, then m
15420 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a in(N,M) bytes.**
15430 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
15440 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 location are cop
15450 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 ied into the beg
15460 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 inning of buffer
15470 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
15480 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
15490 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
154a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
154b0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
154c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
154d0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
154e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
154f0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
15500 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 freed..**.** ^Th
15510 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
15520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
15530 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 loc() and sqlite
15540 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
15550 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
15560 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
15570 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8 byte boundary.
15580 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
15590 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
155a0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
155b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
155c0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
155d0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
155e0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
155f0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
15600 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
15610 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
15620 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
15630 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
15640 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
15650 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
15660 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
15670 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
15680 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
15690 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 ed..**.** The Wi
156a0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
156b0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a ce layer calls.*
156c0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
156d0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
156e0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
156f0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
15700 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
15710 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
15720 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
15730 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
15740 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
15750 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
15760 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
15770 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
15780 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
15790 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
157a0 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 are detected, bu
157b0 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 t.** they are re
157c0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
157d0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
157e0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
157f0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
15800 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
15810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ..**.** The poin
15820 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
15830 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
15840 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
15850 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 ealloc()].** mus
15860 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c t be either NULL
15870 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 or else pointer
15880 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
15890 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 a prior.** invoc
158a0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
158b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
158c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
158d0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
158e0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c not yet been rel
158f0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
15900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
15910 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 t not read or wr
15920 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a ite any part of.
15930 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 ** a block of me
15940 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 mory after it ha
15950 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 s been released
15960 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
15970 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 3_free()] or [sq
15980 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
15990 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
159a0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a e3_malloc(int);.
159b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
159c0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
159d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
159e0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a free(void*);../*
159f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
15a00 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
15a10 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
15a20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
15a30 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
15a40 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
15a50 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
15a60 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
15a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
15a80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
15a90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
15aa0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
15ab0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
15ac0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
15ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15ae0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
15af0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
15b00 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
15b10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
15b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
15b30 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
15b40 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
15b50 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
15b60 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
15b70 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
15b80 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
15b90 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
15ba0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
15bb0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
15bc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
15bd0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
15be0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
15bf0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
15c00 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
15c10 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
15c20 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
15c30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
15c40 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
15c50 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
15c60 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
15c70 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
15c80 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
15c90 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
15ca0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
15cb0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
15cc0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
15cd0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
15ce0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
15cf0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
15d00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
15d10 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
15d20 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
15d30 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
15d40 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
15d50 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
15d60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
15d70 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
15d80 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
15d90 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
15da0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
15db0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
15dc0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
15dd0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
15de0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
15df0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
15e00 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
15e10 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
15e20 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 eset..*/.sqlite3
15e30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
15e40 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 emory_used(void)
15e50 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
15e60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
15e70 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 ighwater(int res
15e80 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 etFlag);../*.**
15e90 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f CAPI3REF: Pseudo
15ea0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 -Random Number G
15eb0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 enerator.**.** S
15ec0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 QLite contains a
15ed0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 high-quality ps
15ee0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 eudo-random numb
15ef0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 er generator (PR
15f00 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 NG) used to.** s
15f10 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f elect random [RO
15f20 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 WID | ROWIDs] wh
15f30 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 en inserting new
15f40 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 records into a
15f50 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c table that.** al
15f60 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c ready uses the l
15f70 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 argest possible
15f80 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 [ROWID]. The PR
15f90 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 NG is also used
15fa0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 for.** the build
15fb0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 -in random() and
15fc0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 randomblob() SQ
15fd0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 L functions. Th
15fe0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
15ff0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ows.** applicati
16000 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
16010 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
16020 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
16030 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f **.** ^A call to
16040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
16050 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
16060 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
16070 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
16080 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
16090 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
160a0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 invoked (either
160b0 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 internally or by
160c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
160d0 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 ion) the PRNG is
160e0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 seeded using ra
160f0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
16100 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 d.** from the xR
16110 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 andomness method
16120 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
16130 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
16140 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c ject..** ^On all
16150 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
16160 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 cations, the pse
16170 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
16180 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
16190 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
161a0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
161b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
161c0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
161d0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
161e0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
161f0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
16200 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
16210 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
16220 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
16230 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
16240 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
16250 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 registers a aut
16260 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16270 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
16280 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
16290 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 connection], sup
162a0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 plied in the fir
162b0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 st argument..**
162c0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
162d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
162e0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 ked as SQL state
162f0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 ments are being
16300 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b compiled.** by [
16310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
16320 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
16330 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ts [sqlite3_prep
16340 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 are_v2()],.** [s
16350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
16360 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
16370 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
16380 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a . ^At various.*
16390 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 * points during
163a0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 the compilation
163b0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 process, as logi
163c0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 c is being creat
163d0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d ed.** to perform
163e0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 various actions
163f0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 , the authorizer
16400 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
16410 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 oked to.** see i
16420 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 f those actions
16430 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 are allowed. ^T
16440 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
16450 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
16460 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
16470 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 OK] to allow the
16480 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 action, [SQLITE
16490 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 _IGNORE] to disa
164a0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 llow the.** spec
164b0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 ific action but
164c0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 allow the SQL st
164d0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 atement to conti
164e0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d nue to be.** com
164f0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 piled, or [SQLIT
16500 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 E_DENY] to cause
16510 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 the entire SQL
16520 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a statement to be.
16530 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 ** rejected with
16540 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 an error. ^If
16550 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
16560 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
16570 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 ** any value oth
16580 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
16590 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 IGNORE], [SQLITE
165a0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 _OK], or [SQLITE
165b0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 _DENY].** then t
165c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
165d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
165e0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
165f0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 t triggered.** t
16600 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 he authorizer wi
16610 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
16620 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
16630 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
16640 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
16650 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 SQLITE_OK], that
16660 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 means the opera
16670 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 tion.** requeste
16680 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 d is ok. ^When
16690 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
166a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e urns [SQLITE_DEN
166b0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 Y], the.** [sqli
166c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
166d0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
166e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
166f0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f red the.** autho
16700 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
16710 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
16720 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 ssage explaining
16730 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 that.** access
16740 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a is denied. .**.*
16750 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
16760 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
16770 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
16780 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
16790 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
167a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
167b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
167c0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e zer() interface.
167d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
167e0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
167f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
16800 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f integer [SQLITE_
16810 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f COPY | action co
16820 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 de] that specifi
16830 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 es.** the partic
16840 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 ular action to b
16850 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 e authorized. ^T
16860 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 he third through
16870 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
16880 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c s.** to the call
16890 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 back are zero-te
168a0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
168b0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 that contain ad
168c0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 ditional.** deta
168d0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
168e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
168f0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rized..**.** ^If
16900 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
16910 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
16920 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
16930 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
16940 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
16950 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
16960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
16970 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
16980 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
16990 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
169a0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
169b0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
169c0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
169d0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
169e0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
169f0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
16a00 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
16a10 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
16a20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
16a30 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
16a40 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
16a50 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
16a60 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
16a70 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 e..** ^If the ac
16a80 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
16a90 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
16aa0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
16ab0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
16ac0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
16ad0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
16ae0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
16af0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
16b00 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
16b10 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
16b20 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
16b30 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
16b40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
16b50 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
16b60 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
16b70 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
16b80 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
16b90 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
16ba0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
16bb0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
16bc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
16bd0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
16be0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
16bf0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
16c00 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
16c10 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
16c20 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
16c30 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
16c40 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
16c50 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
16c60 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
16c70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
16c80 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
16c90 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
16ca0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
16cb0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
16cc0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
16cd0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
16ce0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
16cf0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
16d00 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
16d10 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
16d20 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
16d30 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
16d40 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
16d50 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
16d60 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
16d70 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
16d80 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
16d90 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
16da0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
16db0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
16dc0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
16dd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
16de0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
16df0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
16e00 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
16e10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
16e20 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
16e30 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
16e40 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
16e50 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
16e60 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
16e70 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
16e80 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
16e90 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
16ea0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
16eb0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
16ec0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
16ed0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 er..**.** ^(Only
16ee0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
16ef0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
16f00 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
16f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
16f20 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
16f30 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
16f40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
16f50 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
16f60 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
16f70 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 )^ ^Disable the
16f80 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 authorizer by i
16f90 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c nstalling a NULL
16fa0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 callback..** Th
16fb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 e authorizer is
16fc0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
16fd0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ult..**.** The a
16fe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
16ff0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
17000 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
17010 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
17020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17030 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
17040 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17050 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 callback..** Not
17060 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
17070 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
17080 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
17090 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
170a0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
170b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
170c0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
170d0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
170e0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
170f0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 * ^When [sqlite3
17100 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
17110 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
17120 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
17130 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
17140 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 might be re-prep
17150 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c ared during [sql
17160 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 ite3_step()] due
17170 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 to a .** schema
17180 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c change. Hence,
17190 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
171a0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 should ensure t
171b0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 hat the.** corre
171c0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ct authorizer ca
171d0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 llback remains i
171e0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 n place during t
171f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
17200 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ()]..**.** ^Note
17210 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
17220 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
17230 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 invoked only du
17240 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ring.** [sqlite3
17250 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
17260 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
17270 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
17280 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
17290 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
172a0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
172b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
172c0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 unless.** as st
172d0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 ated in the prev
172e0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 ious paragraph,
172f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
17300 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 nvokes.** sqlite
17310 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 3_prepare_v2() t
17320 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 o reprepare a st
17330 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 atement after a
17340 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a schema change..*
17350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 /.int sqlite3_se
17360 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 t_authorizer(.
17370 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 sqlite3*,. int
17380 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 (*xAuth)(void*,i
17390 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 nt,const char*,c
173a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
173b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
173c0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 r*),. void *pUs
173d0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a erData.);../*.**
173e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
173f0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 rizer Return Cod
17400 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 es.**.** The [sq
17410 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
17420 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
17430 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
17440 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 ion] must.** ret
17450 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 urn either [SQLI
17460 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 TE_OK] or one of
17470 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 these two const
17480 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a ants in order.**
17490 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 to signal SQLit
174a0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 e whether or not
174b0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 the action is p
174c0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 ermitted. See t
174d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 he.** [sqlite3_s
174e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
174f0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d authorizer docum
17500 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 entation] for ad
17510 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
17520 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 rmation..*/.#def
17530 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
17540 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
17550 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
17560 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
17570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17580 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
17590 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
175a0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
175b0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
175c0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
175d0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
175e0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
175f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
17600 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
17610 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
17620 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
17630 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
17640 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
17650 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
17660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
17670 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
17680 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
17690 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
176a0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
176b0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
176c0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
176d0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
176e0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
176f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
17700 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
17710 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
17720 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
17730 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
17740 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
17750 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
17760 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
17770 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
17780 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
17790 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
177a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
177b0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
177c0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
177d0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
177e0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
177f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
17800 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
17810 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
17820 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
17830 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
17840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
17850 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
17860 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
17870 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
17880 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
17890 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
178a0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
178b0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
178c0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
178d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
178e0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
178f0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
17900 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
17910 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
17920 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
17930 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
17940 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
17950 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
17960 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
17970 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
17980 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
17990 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
179a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
179b0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
179c0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
179d0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
179e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
179f0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
17a00 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
17a10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
17a20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17a30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
17a40 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
17a50 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
17a60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
17a70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17a80 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
17a90 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
17aa0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
17ab0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17ad0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
17ae0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
17af0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17b00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17b20 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
17b30 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
17b40 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
17b50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
17b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17b70 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
17b80 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
17b90 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
17ba0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
17bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17bc0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
17bd0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
17be0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
17bf0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
17c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17c10 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
17c20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
17c30 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
17c40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
17c60 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
17c70 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
17c80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
17c90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
17ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
17cb0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
17cc0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
17cd0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
17ce0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
17d00 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
17d10 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
17d20 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
17d30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17d40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
17d50 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
17d60 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
17d70 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
17d80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
17d90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
17da0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
17db0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
17dc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
17dd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
17de0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
17df0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
17e00 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
17e10 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
17e20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17e30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
17e40 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
17e50 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
17e60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
17e70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17e80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
17e90 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
17ea0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
17eb0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
17ec0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17ed0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
17ee0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
17ef0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
17f00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
17f10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17f20 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
17f30 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
17f40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
17f50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
17f60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17f70 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
17f80 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
17f90 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
17fa0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
17fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17fc0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
17fd0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
17fe0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17ff0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
18000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18010 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
18020 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
18030 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
18040 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
18050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18060 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
18070 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
18080 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
18090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
180a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
180b0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
180c0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
180d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
180e0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
180f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
18100 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
18110 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
18120 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
18130 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
18140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
18150 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
18160 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
18170 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
18180 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
181a0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
181b0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
181c0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
181d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
181e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
181f0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
18200 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
18210 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
18220 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
18230 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
18240 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
18250 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
18260 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
18270 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
18280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
18290 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
182a0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
182b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
182c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
182d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
182e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
182f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
18300 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
18310 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
18320 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
18330 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
18340 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
18350 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
18360 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
18370 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
18380 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
18390 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
183a0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
183b0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
183c0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
183d0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
183e0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
183f0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
18400 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
18410 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
18420 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
18430 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
18440 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
18450 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
18460 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
18470 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
18480 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
18490 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
184a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
184b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
184c0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
184d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
184e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a is invoked at.*
184f0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 * various times
18500 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 when an SQL stat
18510 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 ement is being r
18520 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 un by [sqlite3_s
18530 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 tep()]..** ^The
18540 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
18550 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
18560 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 ked with a UTF-8
18570 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
18580 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
18590 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 nt text as the s
185a0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 tatement first b
185b0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e egins executing.
185c0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c .** ^(Additional
185d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
185e0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 callbacks might
185f0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
18600 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
18610 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
18620 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
18630 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
18640 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
18650 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
18660 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
18670 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a e trigger.)^.**.
18680 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
18690 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
186a0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
186b0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
186c0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
186d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
186e0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
186f0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
18700 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
18710 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
18720 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
18730 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
18740 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
18750 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
18760 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
18770 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 run..*/.void *sq
18780 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
18790 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
187a0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
187b0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
187c0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
187d0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
187e0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
187f0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
18800 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
18810 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
18820 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
18830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18840 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
18850 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a s Callbacks.**.*
18860 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
18870 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c configures a cal
18880 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d lback function -
18890 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 the.** progress
188a0 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 callback - that
188b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
188c0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
188d0 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 long.** running
188e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
188f0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
18900 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a te3_step()] and.
18910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
18920 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 table()]. An ex
18930 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
18940 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
18950 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
18960 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
18970 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
18980 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f *.** ^If the pro
18990 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 gress callback r
189a0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
189b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 the operation i
189c0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
189d0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
189e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
189f0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
18a00 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
18a10 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 a GUI progress
18a20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a dialog box..**.*
18a30 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 * The progress h
18a40 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
18a50 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
18a60 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
18a70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
18a80 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
18a90 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 oked the progres
18aa0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f s handler..** No
18ab0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
18ac0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
18ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
18ae0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
18af0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
18b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
18b10 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
18b20 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
18b30 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
18b40 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
18b50 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
18b60 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 (sqlite3*, int,
18b70 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
18b80 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
18b90 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 PI3REF: Opening
18ba0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 A New Database C
18bb0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onnection.**.**
18bc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
18bd0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
18be0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f atabase file who
18bf0 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e se name is given
18c00 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e by the.** filen
18c10 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
18c20 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
18c30 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
18c40 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
18c50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
18c60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
18c70 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
18c80 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
18c90 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
18ca0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
18cb0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
18cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18cd0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
18ce0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
18cf0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
18d00 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
18d10 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
18d20 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
18d30 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
18d40 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
18d50 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
18d60 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
18d70 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
18d80 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
18d90 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
18da0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
18db0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
18dc0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
18dd0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
18de0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
18df0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
18e00 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
18e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
18e20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
18e30 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
18e40 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
18e50 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
18e60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
18e70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
18e80 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
18e90 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
18ea0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
18eb0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
18ec0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
18ed0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
18ee0 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
18ef0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
18f00 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
18f10 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
18f20 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
18f30 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
18f40 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
18f50 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f if.** sqlite3_o
18f60 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
18f70 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 _open_v2() is ca
18f80 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
18f90 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
18fa0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 byte order if s
18fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 qlite3_open16()
18fc0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
18fd0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
18fe0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
18ff0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
19000 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 resources.** as
19010 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
19020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
19030 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 ection] handle s
19040 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
19050 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 d by.** passing
19060 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
19070 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 lose()] when it
19080 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 is no longer req
19090 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
190a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
190b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 () interface wor
190c0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
190d0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 open().** except
190e0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 that it accepts
190f0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
19100 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 parameters for a
19110 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f dditional contro
19120 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 l.** over the ne
19130 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
19140 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c ction. ^(The fl
19150 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
19160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
19170 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f _v2() can take o
19180 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c ne of.** the fol
19190 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c lowing three val
191a0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 ues, optionally
191b0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 combined with th
191c0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 e .** [SQLITE_OP
191d0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
191e0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
191f0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
19200 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c EN_SHAREDCACHE],
19210 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 .** and/or [SQLI
19220 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
19230 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a ACHE] flags:)^.*
19240 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
19250 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
19260 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
19270 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
19280 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
19290 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
192a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
192b0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
192c0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
192d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
192e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
192f0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
19300 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
19310 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
19320 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
19330 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
19340 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
19350 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
19360 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
19370 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
19380 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
19390 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
193a0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
193b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
193c0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
193d0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
193e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
193f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
19400 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
19410 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
19420 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
19430 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
19440 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
19450 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
19460 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
19470 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 , and is creates
19480 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 it if.** it doe
19490 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 s not already ex
194a0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 ist. This is the
194b0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 behavior that i
194c0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f s always used fo
194d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
194e0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
194f0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e open16().</dd>)^
19500 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </dl>.**.**
19510 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
19520 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
19530 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 open_v2() is not
19540 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 one of the.** c
19550 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 ombinations show
19560 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f n above or one o
19570 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f f the combinatio
19580 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 ns shown above c
19590 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 ombined.** with
195a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
195b0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 _NOMUTEX], [SQLI
195c0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
195d0 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f X],.** [SQLITE_O
195e0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
195f0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
19600 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
19610 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e ] flags,.** then
19620 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
19630 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
19640 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
19650 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
19660 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
19670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
19680 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
19690 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
196a0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
196b0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
196c0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
196d0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
196e0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
196f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
19700 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
19710 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
19720 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
19730 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
19740 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
19750 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
19760 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
19770 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
19780 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
19790 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
197a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
197b0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
197c0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
197d0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
197e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
197f0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
19800 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
19810 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
19820 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
19830 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
19840 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
19850 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
19860 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
19870 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
19880 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
19890 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
198a0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
198b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
198c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
198d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
198e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
198f0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
19900 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
19910 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
19920 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
19930 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
19940 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a e filename is ":
19950 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 memory:", then a
19960 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
19970 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ary in-memory da
19980 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 tabase.** is cre
19990 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e ated for the con
199a0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 nection. ^This
199b0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
199c0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 se will vanish w
199d0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 hen.** the datab
199e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
199f0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 s closed. Futur
19a00 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
19a10 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 Lite might.** ma
19a20 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 ke use of additi
19a30 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c onal special fil
19a40 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 enames that begi
19a50 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 n with the ":" c
19a60 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 haracter..** It
19a70 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
19a80 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 hat when a datab
19a90 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 ase filename act
19aa0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e ually does begin
19ab0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 with.** a ":" c
19ac0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f haracter you sho
19ad0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 uld prefix the f
19ae0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 ilename with a p
19af0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a athname such as.
19b00 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 ** "./" to avoid
19b10 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a ambiguity..**.*
19b20 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
19b30 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
19b40 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
19b50 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
19b60 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
19b70 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
19b80 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 ated. ^This pri
19b90 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 vate database wi
19ba0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ll be.** automat
19bb0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 ically deleted a
19bc0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 s soon as the da
19bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19be0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
19bf0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 ** ^The fourth p
19c00 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
19c10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
19c20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
19c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 .** [sqlite3_vfs
19c40 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
19c50 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 fines the operat
19c60 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 ing system inter
19c70 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 face that.** the
19c80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
19c90 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 nnection should
19ca0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f use. ^If the fo
19cb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
19cc0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
19cd0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 ter then the def
19ce0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
19cf0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 s] object is use
19d00 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 d..**.** <b>Note
19d10 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 to Windows user
19d20 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f s:</b> The enco
19d30 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 ding used for th
19d40 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
19d50 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ent.** of sqlite
19d60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
19d70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d ite3_open_v2() m
19d80 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
19d90 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
19da0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
19db0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
19dc0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
19dd0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
19de0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
19df0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
19e00 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
19e10 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
19e20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
19e30 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
19e40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 3_open_v2()..*/.
19e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
19e60 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
19e70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
19e80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
19e90 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
19ea0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
19eb0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
19ec0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
19ed0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
19ee0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 _open16(. const
19ef0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c void *filename,
19f00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
19f10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 ilename (UTF-16)
19f20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
19f30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
19f40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
19f50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
19f60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
19f70 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
19f80 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
19f90 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
19fa0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
19fb0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 lite3 **ppDb,
19fc0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
19fd0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
19fe0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 /. int flags,
19ff0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 /* F
1a000 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 lags */. const
1a010 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 char *zVfs
1a020 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 /* Name of VFS
1a030 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a module to use *
1a040 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
1a050 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 3REF: Error Code
1a060 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a s And Messages.*
1a070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1a080 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 3_errcode() inte
1a090 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
1a0a0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c e numeric [resul
1a0b0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 t code] or.** [e
1a0c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1a0d0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 ode] for the mos
1a0e0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 t recent failed
1a0f0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
1a100 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ll.** associated
1a110 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
1a120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 e connection]. I
1a130 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 f a prior API ca
1a140 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 ll failed.** but
1a150 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1a160 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 API call succee
1a170 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ded, the return
1a180 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 value from.** sq
1a190 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
1a1a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e is undefined. ^
1a1b0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
1a1c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a nded_errcode().*
1a1d0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
1a1e0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 he same except t
1a1f0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 hat it always re
1a200 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 turns the .** [e
1a210 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1a220 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 ode] even when e
1a230 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
1a240 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 odes are.** disa
1a250 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
1a260 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
1a270 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 ) and sqlite3_er
1a280 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 rmsg16() return
1a290 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
1a2a0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 .** text that de
1a2b0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
1a2c0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 r, as either UTF
1a2d0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
1a2e0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 pectively..** ^(
1a2f0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
1a300 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
1a310 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
1a320 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a ed internally..*
1a330 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
1a340 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 n does not need
1a350 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 to worry about f
1a360 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c reeing the resul
1a370 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 t..** However, t
1a380 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 he error string
1a390 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 might be overwri
1a3a0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tten or dealloca
1a3b0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 ted by.** subseq
1a3c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 uent calls to ot
1a3d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
1a3e0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 face functions.)
1a3f0 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ^.**.** When the
1a400 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
1a410 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
1a420 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 in use, it might
1a430 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 be the.** case
1a440 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 that a second er
1a450 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 ror occurs on a
1a460 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
1a470 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 in between.** th
1a480 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 e time of the fi
1a490 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 rst error and th
1a4a0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 e call to these
1a4b0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 interfaces..** W
1a4c0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 hen that happens
1a4d0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 , the second err
1a4e0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 or will be repor
1a4f0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a ted since these.
1a500 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c ** interfaces al
1a510 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 ways report the
1a520 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 most recent resu
1a530 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a lt. To avoid.**
1a540 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 this, each thre
1a550 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 ad can obtain ex
1a560 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 clusive use of t
1a570 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1a580 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 nection] D.** by
1a590 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
1a5a0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 e3_mutex_enter](
1a5b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
1a5c0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 x](D)) before be
1a5d0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 ginning.** to us
1a5e0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 e D and invoking
1a5f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
1a600 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f leave]([sqlite3_
1a610 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 db_mutex](D)) af
1a620 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 ter.** all calls
1a630 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 to the interfac
1a640 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 es listed here a
1a650 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a re completed..**
1a660 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 .** If an interf
1a670 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 ace fails with S
1a680 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 QLITE_MISUSE, th
1a690 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 at means the int
1a6a0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e erface.** was in
1a6b0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c voked incorrectl
1a6c0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 y by the applica
1a6d0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 tion. In that c
1a6e0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f ase, the.** erro
1a6f0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
1a700 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f ge may or may no
1a710 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 t be set..*/.int
1a720 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1a730 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 (sqlite3 *db);.i
1a740 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
1a750 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
1a760 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
1a770 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
1a780 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
1a790 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1a7a0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
1a7b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1a7c0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 API3REF: SQL Sta
1a7d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
1a7e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 KEYWORDS: {prep
1a7f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 ared statement}
1a800 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
1a810 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 ents}.**.** An i
1a820 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
1a830 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
1a840 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 s a single SQL s
1a850 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 tatement..** Thi
1a860 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 s object is vari
1a870 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 ously known as a
1a880 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 "prepared state
1a890 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 ment" or a.** "c
1a8a0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
1a8b0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 ement" or simply
1a8c0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 as a "statement
1a8d0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 "..**.** The lif
1a8e0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 e of a statement
1a8f0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d object goes som
1a900 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 ething like this
1a910 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
1a920 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 <li> Create the
1a930 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
1a940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1a950 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 ()] or a related
1a960 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f .** functio
1a970 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 n..** <li> Bind
1a980 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 values to [host
1a990 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e parameters] usin
1a9a0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
1a9b0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 nd_*().** i
1a9c0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c nterfaces..** <l
1a9d0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 i> Run the SQL b
1a9e0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
1a9f0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f e3_step()] one o
1aa00 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
1aa10 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 <li> Reset the
1aa20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
1aa30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1aa40 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a ] then go back.*
1aa50 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 * to step 2
1aa60 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 . Do this zero
1aa70 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
1aa80 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 * <li> Destroy t
1aa90 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
1aaa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1aab0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a e()]..** </ol>.*
1aac0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f *.** Refer to do
1aad0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 cumentation on i
1aae0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 ndividual method
1aaf0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 s above for addi
1ab00 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
1ab10 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
1ab20 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1ab30 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
1ab40 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
1ab50 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
1ab60 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 mits.**.** ^(Thi
1ab70 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
1ab80 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 ws the size of v
1ab90 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 arious construct
1aba0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a s to be limited.
1abb0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 ** on a connecti
1abc0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e on by connection
1abd0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 basis. The fir
1abe0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
1abf0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
1ac00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f connection] who
1ac10 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 se limit is to b
1ac20 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 e set or queried
1ac30 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
1ac40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e parameter is on
1ac50 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 e of the [limit
1ac60 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 categories] that
1ac70 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 define a.** cla
1ac80 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 ss of constructs
1ac90 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 to be size limi
1aca0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 ted. The third
1acb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
1acc0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f .** new limit fo
1acd0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 r that construct
1ace0 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 . The function
1acf0 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 returns the old
1ad00 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e limit.)^.**.** ^
1ad10 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 If the new limit
1ad20 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e is a negative n
1ad30 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 umber, the limit
1ad40 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a is unchanged..*
1ad50 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69 * ^(For the limi
1ad60 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 t category of SQ
1ad70 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 LITE_LIMIT_XYZ t
1ad80 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c here is a .** [l
1ad90 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 imits | hard upp
1ada0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 er bound].** set
1adb0 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 by a compile-ti
1adc0 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f me C preprocesso
1add0 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a r macro named .*
1ade0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 * [limits | SQLI
1adf0 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 TE_MAX_XYZ]..**
1ae00 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
1ae10 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
1ae20 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
1ae30 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 .))^.** ^Attempt
1ae40 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
1ae50 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
1ae60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
1ae70 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
1ae80 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
1ae90 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 e hard upper bou
1aea0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 nd..**.** Run-ti
1aeb0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
1aec0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
1aed0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
1aee0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
1aef0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
1af00 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
1af10 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
1af20 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
1af30 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
1af40 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
1af50 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
1af60 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
1af70 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
1af80 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
1af90 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
1afa0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
1afb0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
1afc0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
1afd0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
1afe0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
1aff0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
1b000 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
1b010 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
1b020 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
1b030 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
1b040 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
1b050 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
1b060 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
1b070 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
1b080 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
1b090 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
1b0a0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
1b0b0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
1b0c0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
1b0d0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
1b0e0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
1b0f0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
1b100 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1b110 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
1b120 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
1b130 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
1b140 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
1b150 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
1b160 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
1b170 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
1b180 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
1b190 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
1b1a0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
1b1b0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
1b1c0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
1b1d0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
1b1e0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
1b1f0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
1b200 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ses..*/.int sqli
1b210 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 te3_limit(sqlite
1b220 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 3*, int id, int
1b230 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 newVal);../*.**
1b240 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
1b250 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 me Limit Categor
1b260 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ies.** KEYWORDS:
1b270 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
1b280 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f } {*limit catego
1b290 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ries}.**.** Thes
1b2a0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 e constants defi
1b2b0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f ne various perfo
1b2c0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a rmance limits.**
1b2d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 that can be low
1b2e0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 ered at run-time
1b2f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1b300 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 limit()]..** The
1b310 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 synopsis of the
1b320 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
1b330 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 various limits
1b340 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a is shown below..
1b350 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** Additional in
1b360 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 formation is ava
1b370 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 ilable at [limit
1b380 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 s | Limits in SQ
1b390 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c Lite]..**.** <dl
1b3a0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 >.** ^(<dt>SQLIT
1b3b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
1b3c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1b3d0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
1b3e0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
1b3f0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c B or table row.<
1b400 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1b410 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
1b420 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
1b430 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1b440 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
1b450 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
1b460 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
1b470 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 *.** ^(<dt>SQLIT
1b480 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f E_LIMIT_COLUMN</
1b490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1b4a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1b4b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 columns in a ta
1b4c0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f ble definition o
1b4d0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 r in the.** resu
1b4e0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
1b4f0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 ECT] or the maxi
1b500 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
1b510 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 lumns in an inde
1b520 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 x.** or in an OR
1b530 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 DER BY or GROUP
1b540 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 BY clause.</dd>)
1b550 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
1b560 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
1b570 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
1b580 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
1b590 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
1b5a0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
1b5b0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
1b5c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
1b5d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1b5e0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
1b5f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1b600 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
1b610 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
1b620 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1b630 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
1b640 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1b650 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a _VDBE_OP</dt>.**
1b660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1b670 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 number of instr
1b680 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 uctions in a vir
1b690 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f tual machine pro
1b6a0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 gram.** used to
1b6b0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c implement an SQL
1b6c0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
1b6d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1b6e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
1b6f0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a TION_ARG</dt>.**
1b700 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1b710 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
1b720 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 ents on a functi
1b730 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
1b740 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1b750 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
1b760 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1b770 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
1b780 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
1b790 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
1b7a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 /dd>.**.** ^(<dt
1b7b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 >SQLITE_LIMIT_LI
1b7c0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
1b7d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1b7e0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
1b7f0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 of the pattern
1b800 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1b810 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c [LIKE] or.** [GL
1b820 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f OB] operators.</
1b830 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1b840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
1b850 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f ARIABLE_NUMBER</
1b860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1b870 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1b880 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e variables in an
1b890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1b8a0 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f hat can.** be bo
1b8b0 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a und.</dd>)^.**.*
1b8c0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
1b8d0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
1b8e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
1b8f0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
1b900 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f of recursion fo
1b910 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e r triggers.</dd>
1b920 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 )^.** </dl>.*/.#
1b930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1b940 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 MIT_LENGTH
1b950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 0.
1b960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1b970 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 IMIT_SQL_LENGTH
1b980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1b990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b9a0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 LIMIT_COLUMN
1b9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b9c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
1b9d0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
1b9e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
1b9f0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
1ba00 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
1ba10 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
1ba20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
1ba30 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
1ba40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ba50 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
1ba60 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
1ba70 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 ON_ARG
1ba80 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
1ba90 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
1baa0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 HED
1bab0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
1bac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
1bad0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 _PATTERN_LENGTH
1bae0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
1baf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1bb00 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 IABLE_NUMBER
1bb10 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
1bb20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 SQLITE_LIMIT_TR
1bb30 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 IGGER_DEPTH
1bb40 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 10../*.**
1bb50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1bb60 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 ling An SQL Stat
1bb70 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 ement.** KEYWORD
1bb80 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e S: {SQL statemen
1bb90 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a t compiler}.**.*
1bba0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 * To execute an
1bbb0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 SQL query, it mu
1bbc0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 st first be comp
1bbd0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 iled into a byte
1bbe0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d -code.** program
1bbf0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 using one of th
1bc00 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
1bc10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
1bc20 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 gument, "db", is
1bc30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
1bc40 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 nection] obtaine
1bc50 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f d from a.** prio
1bc60 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
1bc70 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 l to [sqlite3_op
1bc80 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1bc90 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a open_v2()] or.**
1bca0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1bcb0 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 ()]. The databa
1bcc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
1bcd0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e st not have been
1bce0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 closed..**.** T
1bcf0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1bd00 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 nt, "zSql", is t
1bd10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 he statement to
1bd20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 be compiled, enc
1bd30 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 oded.** as eithe
1bd40 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
1bd50 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6. The sqlite3_
1bd60 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 prepare() and sq
1bd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1bd80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 ().** interfaces
1bd90 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 use UTF-8, and
1bda0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1bdb0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6() and sqlite3_
1bdc0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a prepare16_v2().*
1bdd0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a * use UTF-16..**
1bde0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 .** ^If the nByt
1bdf0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 e argument is le
1be00 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 ss than zero, th
1be10 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 en zSql is read
1be20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 up to the.** fir
1be30 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1be40 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 or. ^If nByte is
1be50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
1be60 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 hen it is the ma
1be70 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 ximum.** number
1be80 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 of bytes read f
1be90 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e rom zSql. ^When
1bea0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
1beb0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a gative, the.** z
1bec0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 Sql string ends
1bed0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 at either the fi
1bee0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c rst '\000' or '\
1bef0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 u0000' character
1bf00 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 or.** the nByte
1bf10 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 -th byte, whiche
1bf20 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e ver comes first.
1bf30 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b If the caller k
1bf40 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 nows.** that the
1bf50 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 supplied string
1bf60 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 is nul-terminat
1bf70 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 ed, then there i
1bf80 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 s a small.** per
1bf90 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 formance advanta
1bfa0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 ge to be gained
1bfb0 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 by passing an nB
1bfc0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 yte parameter th
1bfd0 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 at.** is equal t
1bfe0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 o the number of
1bff0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 bytes in the inp
1c000 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 ut string <i>inc
1c010 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 luding</i>.** th
1c020 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 e nul-terminator
1c030 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 bytes..**.** ^I
1c040 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 f pzTail is not
1c050 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 NULL then *pzTai
1c060 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
1c070 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 nt to the first
1c080 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 byte.** past the
1c090 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 end of the firs
1c0a0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
1c0b0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 in zSql. These
1c0c0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a routines only.**
1c0d0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
1c0e0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 st statement in
1c0f0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
1c100 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
1c110 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d g to.** what rem
1c120 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e ains uncompiled.
1c130 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 .**.** ^*ppStmt
1c140 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
1c150 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
1c160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c170 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
1c180 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
1c190 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1c1a0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 )]. ^If there i
1c1b0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
1c1c0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f tmt is set.** to
1c1d0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 NULL. ^If the
1c1e0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
1c1f0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
1c200 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
1c210 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
1c220 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
1c230 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
1c240 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
1c250 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
1c260 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
1c270 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
1c280 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
1c290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
1c2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
1c2b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
1c2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
1c2d0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
1c2e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
1c2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 ..**.** ^On succ
1c300 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ess, the sqlite3
1c310 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c _prepare() famil
1c320 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 y of routines re
1c330 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
1c340 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 ;.** otherwise a
1c350 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
1c360 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
1c370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 * The sqlite3_pr
1c380 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 epare_v2() and s
1c390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1c3a0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 _v2() interfaces
1c3b0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e are.** recommen
1c3c0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 ded for all new
1c3d0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 programs. The tw
1c3e0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 o older interfac
1c3f0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a es are retained.
1c400 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ** for backwards
1c410 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 compatibility,
1c420 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 but their use is
1c430 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a discouraged..**
1c440 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e ^In the "v2" in
1c450 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 terfaces, the pr
1c460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1c470 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 .** that is retu
1c480 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 rned (the [sqlit
1c490 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 e3_stmt] object)
1c4a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 contains a copy
1c4b0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 of the.** origi
1c4c0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 nal SQL text. Th
1c4d0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 is causes the [s
1c4e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 qlite3_step()] i
1c4f0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 nterface to.** b
1c500 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c ehave differentl
1c510 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a y in three ways:
1c520 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
1c530 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 li>.** ^If the d
1c540 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
1c550 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 hanges, instead
1c560 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 of returning [SQ
1c570 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 LITE_SCHEMA] as
1c580 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 it.** always use
1c590 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 d to do, [sqlite
1c5a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 3_step()] will a
1c5b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
1c5c0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a ompile the SQL.*
1c5d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 * statement and
1c5e0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 try to run it ag
1c5f0 61 69 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 ain. ^If the sc
1c600 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 hema has changed
1c610 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 in.** a way tha
1c620 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 t makes the stat
1c630 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 ement no longer
1c640 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f valid, [sqlite3_
1c650 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 step()] will sti
1c660 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
1c670 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 LITE_SCHEMA]. B
1c680 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 ut unlike the le
1c690 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b gacy behavior, [
1c6a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 SQLITE_SCHEMA] i
1c6b0 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c s.** now a fatal
1c6c0 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 error. Calling
1c6d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1c6e0 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 e_v2()] again wi
1c6f0 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a ll not make the.
1c700 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 ** error go away
1c710 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 . Note: use [sq
1c720 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
1c730 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 to find the text
1c740 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 .** of the parsi
1c750 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 ng error that re
1c760 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c sults in an [SQL
1c770 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 ITE_SCHEMA] retu
1c780 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a rn..** </li>.**.
1c790 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
1c7a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1c7b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1c7c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
1c7d0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
1c7e0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
1c7f0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
1c800 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
1c810 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
1c820 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
1c830 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1c840 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
1c850 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
1c860 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
1c870 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
1c880 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1c890 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
1c8a0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
1c8b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
1c8c0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
1c8d0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
1c8e0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
1c8f0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
1c900 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
1c910 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
1c920 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
1c930 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
1c940 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
1c950 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
1c960 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
1c970 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
1c980 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 value of a [para
1c990 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 meter | host par
1c9a0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 ameter] in the W
1c9b0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 HERE clause migh
1c9c0 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 t.** change the
1c9d0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
1c9e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e statement, then
1c9f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d the statement m
1ca00 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ay be.** automat
1ca10 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
1ca20 64 20 28 61 73 20 69 66 20 74 68 65 72 65 20 68 d (as if there h
1ca30 61 64 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 ad been a schema
1ca40 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 change) on the
1ca50 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 first .** [sqlit
1ca60 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
1ca70 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 following any ch
1ca80 61 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 ange to the .**
1ca90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
1caa0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
1cab0 66 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 f the [parameter
1cac0 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ]. .** </li>.**
1cad0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c </ol>.*/.int sql
1cae0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 ite3_prepare(.
1caf0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1cb00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1cb10 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1cb20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1cb30 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1cb40 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
1cb50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1cb60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1cb70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1cb80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1cb90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1cba0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1cbb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1cbc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1cbd0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1cbe0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1cbf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1cc00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1cc10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
1cc20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1cc30 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
1cc40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1cc50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1cc60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1cc70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1cc80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1cc90 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
1cca0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1ccb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1ccc0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1ccd0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1cce0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1ccf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1cd00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1cd10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1cd20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
1cd30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1cd40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1cd50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1cd60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1cd70 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 epare16(. sqlit
1cd80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1cd90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
1cda0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1cdb0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
1cdc0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
1cdd0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
1cde0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1cdf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1ce00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1ce10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1ce20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1ce30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1ce40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1ce50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1ce60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
1ce70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1ce80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1ce90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1cea0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1ceb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1cec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1ced0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
1cee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
1cef0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
1cf00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
1cf10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
1cf20 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
1cf30 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
1cf40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
1cf50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
1cf60 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
1cf70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
1cf80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
1cf90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
1cfa0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
1cfb0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
1cfc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
1cfd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
1cfe0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
1cff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d000 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
1d010 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a tement SQL.**.**
1d020 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
1d030 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1d040 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 retrieve a saved
1d050 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 copy of the ori
1d060 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 ginal.** SQL tex
1d070 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 t used to create
1d080 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1d090 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 tement] if that
1d0a0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a statement was.**
1d0b0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 compiled using
1d0c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
1d0d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1d0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1d0f0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f e16_v2()]..*/.co
1d100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1d110 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 3_sql(sqlite3_st
1d120 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
1d130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
1d140 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
1d150 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
1d160 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
1d170 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1d180 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
1d190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
1d1a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
1d1b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
1d1c0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
1d1d0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
1d1e0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
1d1f0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
1d200 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
1d210 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
1d220 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
1d230 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
1d240 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
1d250 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
1d260 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
1d270 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
1d280 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
1d290 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
1d2a0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
1d2b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
1d2c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1d2d0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
1d2e0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
1d2f0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
1d300 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
1d310 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
1d320 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1d330 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
1d340 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
1d350 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
1d360 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
1d370 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1d380 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
1d390 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
1d3a0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
1d3b0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
1d3c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
1d3d0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
1d3e0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
1d3f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1d400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
1d410 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
1d420 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
1d430 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
1d440 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
1d450 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
1d460 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
1d470 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
1d480 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1d490 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
1d4a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
1d4b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
1d4c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1d4d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
1d4e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1d4f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
1d500 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
1d510 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
1d520 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
1d530 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
1d540 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
1d550 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
1d560 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
1d570 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
1d580 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
1d590 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1d5a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
1d5b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1d5c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
1d5d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
1d5e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
1d5f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
1d600 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
1d610 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1d620 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
1d630 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
1d640 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
1d650 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
1d660 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
1d670 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
1d680 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
1d690 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
1d6a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
1d6b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
1d6c0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
1d6d0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
1d6e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
1d6f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
1d700 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
1d710 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
1d720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1d730 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 _value objects t
1d740 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 hat are passed a
1d750 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 s parameters int
1d760 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 o the.** impleme
1d770 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c ntation of [appl
1d780 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
1d790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 SQL functions] a
1d7a0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a re protected..**
1d7b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
1d7c0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 lue object retur
1d7d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
1d7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
1d7f0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 )] is unprotecte
1d800 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 d..** Unprotecte
1d810 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
1d820 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 objects may only
1d830 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a be used with.**
1d840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
1d850 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
1d860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
1d870 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
1d880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
1d890 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 | sqlite3_value
1d8a0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 _type()] family
1d8b0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
1d8c0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 require protect
1d8d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1d8e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 objects..*/.typ
1d8f0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 edef struct Mem
1d900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a sqlite3_value;..
1d910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1d920 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e SQL Function Con
1d930 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a text Object.**.*
1d940 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
1d950 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
1d960 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
1d970 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
1d980 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
1d990 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 xt object. ^A p
1d9a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
1d9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
1d9c0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ect.** is always
1d9d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1d9e0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e to [application
1d9f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1da00 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 ctions]..** The
1da10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
1da20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
1da30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1da40 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a will pass this.*
1da50 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 * pointer throug
1da60 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 h into calls to
1da70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
1da80 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 int | sqlite3_re
1da90 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sult()],.** [sql
1daa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
1dab0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 ontext()], [sqli
1dac0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
1dad0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f ,.** [sqlite3_co
1dae0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
1daf0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 )], [sqlite3_get
1db00 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 _auxdata()],.**
1db10 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f and/or [sqlite3_
1db20 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a set_auxdata()]..
1db30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1db40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
1db50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
1db60 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
1db70 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 EF: Binding Valu
1db80 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 es To Prepared S
1db90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 tatements.** KEY
1dba0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
1dbb0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
1dbc0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
1dbd0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
1dbe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
1dbf0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
1dc00 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
1dc10 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
1dc20 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 }.**.** ^(In the
1dc30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1dc40 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
1dc50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1dc60 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
1dc70 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
1dc80 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
1dc90 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
1dca0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
1dcb0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
1dcc0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
1dcd0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
1dce0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
1dcf0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
1dd00 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
1dd10 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
1dd20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
1dd30 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
1dd40 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
1dd50 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
1dd60 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
1dd70 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
1dd80 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
1dd90 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 ntifer.)^ ^The
1dda0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
1ddb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
1ddc0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
1ddd0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
1dde0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
1ddf0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
1de00 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
1de10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
1de20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
1de30 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
1de40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1de50 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1de60 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1de70 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
1de80 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1de90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
1dea0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
1deb0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
1dec0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1ded0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
1dee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
1def0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
1df00 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
1df10 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
1df20 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
1df30 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
1df40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
1df50 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
1df60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
1df70 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
1df80 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
1df90 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
1dfa0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
1dfb0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
1dfc0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
1dfd0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
1dfe0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
1dff0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
1e000 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
1e010 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
1e020 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
1e030 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1e040 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
1e050 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
1e060 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
1e070 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
1e080 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1e090 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
1e0a0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
1e0b0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
1e0c0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
1e0d0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
1e0e0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
1e0f0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
1e100 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
1e110 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
1e120 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
1e130 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
1e140 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
1e150 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 meter..**.** ^(I
1e160 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 n those routines
1e170 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 that have a fou
1e180 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 rth argument, it
1e190 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a s value is the.*
1e1a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
1e1b0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 s in the paramet
1e1c0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 er. To be clear
1e1d0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 : the value is t
1e1e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
1e1f0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 <u>bytes</u> in
1e200 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 the value, not t
1e210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
1e220 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 racters.)^.** ^I
1e230 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
1e240 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 ameter is negati
1e250 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f ve, the length o
1e260 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
1e270 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
1e280 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
1e290 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
1e2a0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 inator..**.** ^T
1e2b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
1e2c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
1e2d0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
1e2e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
1e2f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
1e300 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
1e310 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
1e320 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
1e330 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
1e340 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
1e350 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
1e360 69 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 ith it. ^If the
1e370 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 fifth argument i
1e380 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c s.** the special
1e390 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 value [SQLITE_S
1e3a0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c TATIC], then SQL
1e3b0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
1e3c0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 the.** informat
1e3d0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 ion is in static
1e3e0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 , unmanaged spac
1e3f0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e e and does not n
1e400 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e eed to be freed.
1e410 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
1e420 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 h argument has t
1e430 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 he value [SQLITE
1e440 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
1e450 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 n.** SQLite make
1e460 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 s its own privat
1e470 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 e copy of the da
1e480 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ta immediately,
1e490 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 before.** the sq
1e4a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
1e4b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a outine returns..
1e4c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e4d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
1e4e0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
1e4f0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
1e500 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
1e510 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
1e520 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 s. ^A zeroblob
1e530 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f uses a fixed amo
1e540 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a unt of memory.**
1e550 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 (just an intege
1e560 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 r to hold its si
1e570 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 ze) while it is
1e580 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e being processed.
1e590 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 .** Zeroblobs ar
1e5a0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 e intended to se
1e5b0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 rve as placehold
1e5c0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 ers for BLOBs wh
1e5d0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 ose.** content i
1e5e0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 s later written
1e5f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
1e600 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 3_blob_open | in
1e610 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 cremental BLOB I
1e620 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a /O] routines..**
1e630 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c ^A negative val
1e640 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
1e650 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
1e660 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
1e670 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 B..**.** ^If any
1e680 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
1e690 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1e6a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 s are called wit
1e6b0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1e6c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 .** for the [pre
1e6d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1e6e0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 or with a prepa
1e6f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f red statement fo
1e700 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 r which.** [sqli
1e710 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
1e720 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 been called more
1e730 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b recently than [
1e740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1e750 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 ,.** then the ca
1e760 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ll will return [
1e770 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
1e780 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f If any sqlite3_
1e790 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 bind_().** routi
1e7a0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b ne is passed a [
1e7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e7c0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 nt] that has bee
1e7d0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 n finalized, the
1e7e0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e .** result is un
1e7f0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
1e800 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ably harmful..**
1e810 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 .** ^Bindings ar
1e820 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
1e830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
1e840 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
1e850 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 ** ^Unbound para
1e860 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 meters are inter
1e870 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a preted as NULL..
1e880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e890 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e e3_bind_* routin
1e8a0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
1e8b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
1e8c0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 or an.** [error
1e8d0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 code] if anythi
1e8e0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a ng goes wrong..*
1e8f0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 * ^[SQLITE_RANGE
1e900 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1e910 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a the parameter.*
1e920 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f * index is out o
1e930 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 f range. ^[SQLI
1e940 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 TE_NOMEM] is ret
1e950 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 urned if malloc(
1e960 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 ) fails..**.** S
1e970 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1e980 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e990 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 _count()],.** [s
1e9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e9b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
1e9c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
1e9d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1e9e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1e9f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 te3_bind_blob(sq
1ea00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1ea10 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
1ea20 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
1ea30 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
1ea40 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
1ea50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1ea60 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 t, double);.int
1ea70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
1ea80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1ea90 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 int, int);.int s
1eaa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
1eab0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
1eac0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
1ead0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t64);.int sqlite
1eae0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
1eaf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1eb00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1eb10 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
1eb20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1eb30 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
1eb40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1eb50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1eb60 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
1eb70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
1eb80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
1eb90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
1eba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1ebb0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
1ebc0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1ebd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
1ebe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1ebf0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 d_zeroblob(sqlit
1ec00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
1ec10 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt n);../*.** CA
1ec20 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
1ec30 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
1ec40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1ec50 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 tine can be used
1ec60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
1ec70 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 ber of [SQL para
1ec80 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 meters].** in a
1ec90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1eca0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d ent]. SQL param
1ecb0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 eters are tokens
1ecc0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 of the.** form
1ecd0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 "?", "?NNN", ":A
1ece0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 AA", "$AAA", or
1ecf0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 "@AAA" that serv
1ed00 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c e as.** placehol
1ed10 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 ders for values
1ed20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 that are [sqlite
1ed30 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 3_bind_blob | bo
1ed40 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 und].** to the p
1ed50 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c arameters at a l
1ed60 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a ater time..**.**
1ed70 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
1ed80 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 actually returns
1ed90 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
1eda0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 e largest (right
1edb0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 most).** paramet
1edc0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d er. For all form
1edd0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 s except ?NNN, t
1ede0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 his will corresp
1edf0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 ond to the.** nu
1ee00 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 mber of unique p
1ee10 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 arameters. If p
1ee20 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1ee30 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 ?NNN form are u
1ee40 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 sed,.** there ma
1ee50 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 y be gaps in the
1ee60 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 list.)^.**.** S
1ee70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1ee80 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
1ee90 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
1eea0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1eeb0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
1eec0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1eed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1eee0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 index()]..*/.int
1eef0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
1ef00 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 rameter_count(sq
1ef10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
1ef20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
1ef30 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 ame Of A Host Pa
1ef40 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 rameter.**.** ^T
1ef50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1ef60 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
1ef70 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
1ef80 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
1ef90 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
1efa0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
1efb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1efc0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
1efd0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
1efe0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
1eff0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
1f000 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
1f010 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
1f020 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
1f030 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
1f040 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
1f050 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
1f060 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
1f070 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
1f080 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
1f090 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
1f0a0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
1f0b0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
1f0c0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
1f0d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
1f0e0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
1f0f0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
1f100 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
1f110 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
1f120 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
1f130 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
1f140 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
1f150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
1f160 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
1f170 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
1f180 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
1f190 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
1f1a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1f1b0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
1f1c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
1f1d0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
1f1e0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
1f1f0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
1f200 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
1f210 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
1f220 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
1f230 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
1f240 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
1f250 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
1f260 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
1f270 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1f280 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
1f290 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1f2a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1f2b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
1f2c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
1f2d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1f2e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1f2f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
1f300 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1f310 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1f320 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 ]..*/.const char
1f330 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 *sqlite3_bind_p
1f340 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 arameter_name(sq
1f350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1f360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f370 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 EF: Index Of A P
1f380 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 arameter With A
1f390 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a Given Name.**.**
1f3a0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
1f3b0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
1f3c0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
1f3d0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
1f3e0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
1f3f0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
1f400 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
1f410 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
1f420 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
1f430 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
1f440 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
1f450 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
1f460 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
1f470 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
1f480 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
1f490 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
1f4a0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
1f4b0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
1f4c0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
1f4d0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
1f4e0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
1f4f0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
1f500 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1f510 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
1f520 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
1f530 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1f540 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
1f550 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1f560 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
1f570 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
1f580 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
1f590 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ex()]..*/.int sq
1f5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1f5b0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 eter_index(sqlit
1f5c0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 e3_stmt*, const
1f5d0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f char *zName);../
1f5e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1f5f0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 eset All Binding
1f600 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 s On A Prepared
1f610 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
1f620 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 ^Contrary to the
1f630 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
1f640 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
1f650 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
1f660 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
1f670 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
1f680 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
1f690 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f6a0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 ent]..** ^Use th
1f6b0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 is routine to re
1f6c0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 set all host par
1f6d0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e ameters to NULL.
1f6e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f6f0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 clear_bindings(s
1f700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
1f710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f720 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e Number Of Column
1f730 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
1f740 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 t.**.** ^Return
1f750 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
1f760 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
1f770 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
1f780 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 by the.** [prep
1f790 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
1f7a0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
1f7b0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d eturns 0 if pStm
1f7c0 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 t is an SQL.** s
1f7d0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f tatement that do
1f7e0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 es not return da
1f7f0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ta (for example
1f800 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f an [UPDATE])..*/
1f810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
1f820 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
1f830 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
1f840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f850 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
1f860 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
1f870 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
1f880 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e nes return the n
1f890 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
1f8a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c a particular col
1f8b0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 umn.** in the re
1f8c0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
1f8d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1f8e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
1f8f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
1f900 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1f910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1f920 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1f930 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
1f940 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
1f950 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
1f960 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1f970 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
1f980 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
1f990 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 tring. ^The fir
1f9a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
1f9b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
1f9c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 atement].** that
1f9d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
1f9e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
1f9f0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 nt. ^The second
1fa00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
1fa10 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 .** column numbe
1fa20 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 r. ^The leftmos
1fa30 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
1fa40 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er 0..**.** ^The
1fa50 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
1fa60 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 pointer is vali
1fa70 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 d until either t
1fa80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
1fa90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 tement].** is de
1faa0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
1fab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
1fac0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 or until the nex
1fad0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c t call to.** sql
1fae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1faf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
1fb00 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e lumn_name16() on
1fb10 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
1fb20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ..**.** ^If sqli
1fb30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
1fb40 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
1fb50 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
1fb60 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
1fb70 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
1fb80 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
1fb90 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
1fba0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
1fbb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
1fbc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
1fbd0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
1fbe0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
1fbf0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
1fc00 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
1fc10 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
1fc20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
1fc30 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
1fc40 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
1fc50 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
1fc60 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
1fc70 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
1fc80 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
1fc90 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
1fca0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
1fcb0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 o the next..*/.c
1fcc0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1fcd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
1fce0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1fcf0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
1fd00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1fd10 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1fd20 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
1fd30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1fd40 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
1fd50 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
1fd60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1fd70 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 utines provide a
1fd80 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d means to determ
1fd90 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ine the database
1fda0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 , table, and.**
1fdb0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
1fdc0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 t is the origin
1fdd0 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 of a particular
1fde0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e result column in
1fdf0 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 .** [SELECT] sta
1fe00 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 tement..** ^The
1fe10 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
1fe20 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 base or table or
1fe30 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 column can be r
1fe40 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 eturned as.** ei
1fe50 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 ther a UTF-8 or
1fe60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
1fe70 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 ^The _database_
1fe80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a routines return.
1fe90 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1fea0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 name, the _table
1feb0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
1fec0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 n the table name
1fed0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 , and.** the ori
1fee0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 gin_ routines re
1fef0 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 turn the column
1ff00 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 name..** ^The re
1ff10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
1ff20 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
1ff30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ff40 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 ment] is destroy
1ff50 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
1ff60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1ff70 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
1ff80 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
1ff90 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
1ffa0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
1ffb0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
1ffc0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
1ffd0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
1ffe0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
1fff0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
20000 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
20010 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
20020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
20030 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
20040 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
20050 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
20060 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
20070 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
20080 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
20090 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
200a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
200b0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
200c0 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
200d0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
200e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
200f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
20100 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
20110 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
20120 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
20130 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
20140 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
20150 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
20160 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
20170 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
20180 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
20190 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
201a0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
201b0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
201c0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
201d0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
201e0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
201f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
20200 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
20210 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
20220 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
20230 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
20240 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
20250 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
20260 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
20270 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
20280 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
20290 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
202a0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
202b0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
202c0 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
202d0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
202e0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
202f0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
20300 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
20310 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
20320 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
20330 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
20340 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
20350 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
20360 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
20370 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
20380 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
20390 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
203a0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
203b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
203c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
203d0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
203e0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
203f0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
20400 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
20410 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
20420 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
20430 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
20440 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
20450 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
20460 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
20470 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
20480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
20490 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
204a0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
204b0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
204c0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
204d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
204e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
204f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
20500 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
20510 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
20520 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
20530 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
20540 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
20550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
20560 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
20570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
20580 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
20590 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
205a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
205b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
205c0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
205d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
205e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
205f0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
20600 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
20610 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
20620 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
20630 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
20640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
20650 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
20660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
20670 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
20680 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
20690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
206a0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
206b0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
206c0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ult.**.** ^(The
206d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
206e0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
206f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
20700 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 this statement
20710 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 is a [SELECT] st
20720 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 atement and the
20730 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
20740 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 e.** returned re
20750 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 sult set of that
20760 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 [SELECT] is a t
20770 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 able column (not
20780 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
20790 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 n or subquery) t
207a0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 hen the declared
207b0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 type of the tab
207c0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 le.** column is
207d0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 returned.)^ ^If
207e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
207f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
20800 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
20810 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
20820 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
20830 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
20840 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 ed..** ^The retu
20850 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
20860 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
20870 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
20880 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 example, given
20890 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
208a0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 ema:.**.** CREAT
208b0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 E TABLE t1(c1 VA
208c0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e RIANT);.**.** an
208d0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 d the following
208e0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
208f0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 compiled:.**.**
20900 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 SELECT c1 + 1, c
20910 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 1 FROM t1;.**.**
20920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f this routine wo
20930 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 uld return the s
20940 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 tring "VARIANT"
20950 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 for the second r
20960 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 esult.** column
20970 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 (i==1), and a NU
20980 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 LL pointer for t
20990 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 he first result
209a0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e column (i==0).)^
209b0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
209c0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
209d0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 time typing. ^S
209e0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 o just because a
209f0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 column.** is de
20a00 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 clared to contai
20a10 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 n a particular t
20a20 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 ype does not mea
20a30 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 n that the.** da
20a40 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 ta stored in tha
20a50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 t column is of t
20a60 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
20a70 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 . SQLite is.**
20a80 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 strongly typed,
20a90 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 but the typing i
20aa0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 s dynamic not st
20ab0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 atic. ^Type.**
20ac0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
20ad0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
20ae0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
20af0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
20b00 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
20b10 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 ose values..*/.c
20b20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
20b30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
20b40 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
20b50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
20b60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
20b70 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c n_decltype16(sql
20b80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
20b90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20ba0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 : Evaluate An SQ
20bb0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a L Statement.**.*
20bc0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
20bd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
20be0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
20bf0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
20c00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20c10 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
20c20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
20c30 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
20c40 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
20c50 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
20c60 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
20c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20c80 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
20c90 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
20ca0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
20cb0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
20cc0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
20cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
20ce0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
20cf0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
20d00 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
20d10 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
20d20 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
20d30 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
20d40 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
20d50 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
20d60 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
20d70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
20d80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20d90 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
20da0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
20db0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
20dc0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
20dd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
20de0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
20df0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
20e00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
20e10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
20e20 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
20e30 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
20e40 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
20e50 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
20e60 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
20e70 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
20e80 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
20e90 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
20ea0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
20eb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
20ec0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
20ed0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
20ee0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
20ef0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
20f00 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
20f10 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
20f20 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
20f30 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
20f40 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
20f50 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
20f60 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
20f70 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
20f80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
20f90 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
20fa0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
20fb0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
20fc0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
20fd0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
20fe0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
20ff0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
21000 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
21010 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
21020 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
21030 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
21040 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
21050 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
21060 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
21070 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
21080 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
21090 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a ccurs within a.*
210a0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 * explicit trans
210b0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 action then you
210c0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 should rollback
210d0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
210e0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e before.** contin
210f0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 uing..**.** ^[SQ
21100 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 LITE_DONE] means
21110 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d that the statem
21120 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 ent has finished
21130 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 executing.** su
21140 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c ccessfully. sql
21150 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
21160 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
21170 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 again on this v
21180 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
21190 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 e without first
211a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
211b0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 _reset()] to res
211c0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a et the virtual.*
211d0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 * machine back t
211e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
211f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ate..**.** ^If t
21200 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
21210 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 being executed
21220 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 returns any data
21230 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 , then [SQLITE_R
21240 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e OW].** is return
21250 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e ed each time a n
21260 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 ew row of data i
21270 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 s ready for proc
21280 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a essing by the.**
21290 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c caller. The val
212a0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 ues may be acces
212b0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 sed using the [c
212c0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
212d0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 ctions]..** sqli
212e0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 te3_step() is ca
212f0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 lled again to re
21300 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 trieve the next
21310 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a row of data..**.
21320 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f ** ^[SQLITE_ERRO
21330 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
21340 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
21350 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
21360 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
21370 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
21380 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
21390 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
213a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
213b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
213c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
213d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
213e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
213f0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 sg()]..** ^With
21400 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
21410 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 face, a more spe
21420 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
21430 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a (for example,.*
21440 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 * [SQLITE_INTERR
21450 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 UPT], [SQLITE_SC
21460 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 HEMA], [SQLITE_C
21470 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 ORRUPT], and so
21480 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 forth).** can be
21490 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c obtained by cal
214a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
214b0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a set()] on the.**
214c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
214d0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 ment]. ^In the
214e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a "v2" interface,.
214f0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 ** the more spec
21500 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
21510 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 is returned dire
21520 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ctly by sqlite3_
21530 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 step()..**.** [S
21540 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 QLITE_MISUSE] me
21550 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 ans that the thi
21560 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 s routine was ca
21570 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 lled inappropria
21580 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 tely..** Perhaps
21590 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f it was called o
215a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
215b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
215c0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
215d0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
215e0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
215f0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
21600 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c had.** previousl
21610 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 y returned [SQLI
21620 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 TE_ERROR] or [SQ
21630 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 LITE_DONE]. Or
21640 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 it could.** be t
21650 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
21660 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
21670 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 onnection is bei
21680 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f ng used by two o
21690 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 r.** more thread
216a0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f s at the same mo
216b0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a ment in time..**
216c0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
216d0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
216e0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
216f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
21700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
21710 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
21720 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
21730 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
21740 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
21750 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
21760 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
21770 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
21780 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
21790 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
217a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
217b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
217c0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
217d0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
217e0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
217f0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
21800 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
21810 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
21820 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
21830 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
21840 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
21850 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
21860 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
21870 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
21880 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
21890 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
218a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
218b0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
218c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
218d0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
218e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
218f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
21900 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
21910 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
21920 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
21930 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
21940 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
21950 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
21960 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
21970 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
21980 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
21990 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
219a0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
219b0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
219c0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ended..*/.int sq
219d0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
219e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
219f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
21a00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
21a10 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
21a20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
21a30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 _data_count(P) t
21a40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
21a50 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f umns in the.** o
21a60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
21a70 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
21a80 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 atement] P..*/.i
21a90 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f nt sqlite3_data_
21aa0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
21ab0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
21ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
21ad0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 damental Datatyp
21ae0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
21af0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
21b00 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 * ^(Every value
21b10 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
21b20 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
21b30 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
21b40 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
21b50 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
21b60 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
21b70 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
21b80 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
21b90 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
21ba0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
21bb0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
21bc0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
21bd0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
21be0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
21bf0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
21c00 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
21c10 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
21c20 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
21c30 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
21c40 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
21c50 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
21c60 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
21c70 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
21c80 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
21c90 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
21ca0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
21cb0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
21cc0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
21cd0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
21ce0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
21cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
21d00 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
21d10 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
21d20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
21d30 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
21d40 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
21d50 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
21d60 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
21d70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
21d80 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
21d90 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
21da0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
21db0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
21dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21dd0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
21de0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b rom A Query.** K
21df0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
21e00 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
21e10 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
21e20 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
21e30 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e "result set" in
21e40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
21e50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
21e60 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
21e70 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
21e80 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
21e90 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
21ea0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
21eb0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
21ec0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
21ed0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
21ee0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
21ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
21f00 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
21f10 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
21f20 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
21f30 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
21f40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
21f50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
21f60 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
21f70 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
21f80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
21f90 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
21fa0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
21fb0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
21fc0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
21fd0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
21fe0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
21ff0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
22000 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
22010 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
22020 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
22030 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
22040 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
22050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
22060 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
22070 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
22080 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
22090 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
220a0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
220b0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
220c0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
220d0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
220e0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
220f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
22100 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
22110 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
22120 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
22130 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
22140 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
22150 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
22160 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
22170 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
22180 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
22190 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
221a0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
221b0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
221c0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
221d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
221e0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
221f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
22200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
22210 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
22220 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
22230 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
22240 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
22250 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
22260 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
22270 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
22280 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
22290 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
222a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
222b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
222c0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
222d0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
222e0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
222f0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
22300 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
22310 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
22320 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
22330 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
22340 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
22350 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
22360 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
22370 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
22380 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
22390 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
223a0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
223b0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
223c0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
223d0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
223e0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
223f0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
22400 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
22410 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
22420 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
22430 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
22440 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
22450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22460 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
22470 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
22480 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
22490 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
224a0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
224b0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
224c0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
224d0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
224e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
224f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
22500 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
22510 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
22520 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
22530 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
22540 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
22550 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
22560 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
22570 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
22580 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
22590 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
225a0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
225b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
225c0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
225d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
225e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
225f0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
22600 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
22610 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
22620 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
22630 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
22640 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
22650 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
22660 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
22670 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
22680 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
22690 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
226a0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
226b0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
226c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
226d0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
226e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
226f0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
22700 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
22710 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
22720 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
22730 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
22740 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 at string..** ^T
22750 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
22760 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
22770 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
22780 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e inator at the en
22790 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
227a0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 ng. ^For clarit
227b0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 y: the value ret
227c0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d urned is the num
227d0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
227e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
227f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
22800 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
22810 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 ** ^Strings retu
22820 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
22830 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
22840 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
22850 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
22860 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
22870 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
22880 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o terminated. ^
22890 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
228a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
228b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
228c0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
228d0 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 BLOB is an arbi
228e0 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 trary.** pointer
228f0 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 , possibly even
22900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
22910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
22920 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
22930 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 6() routine is s
22940 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 imilar to sqlite
22950 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
22960 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 .** but leaves t
22970 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 he result in UTF
22980 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
22990 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 te order instead
229a0 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 of UTF-8..** ^T
229b0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
229c0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 or is not includ
229d0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 ed in this count
229e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a ..**.** ^The obj
229f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 ect returned by
22a00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
22a10 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a value()] is an.*
22a20 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
22a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
22a40 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 ject. An unprot
22a50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22a60 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 lue object.** ma
22a70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
22a80 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e ith [sqlite3_bin
22a90 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
22aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
22ab0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
22ac0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
22ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
22ae0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
22af0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
22b00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
22b10 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
22b20 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
22b30 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
22b40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
22b50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
22b60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
22b70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
22b80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
22b90 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 bytes()], then t
22ba0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
22bb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
22bc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
22bd0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
22be0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
22bf0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
22c00 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
22c10 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
22c20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
22c30 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
22c40 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
22c50 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
22c60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
22c70 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
22c80 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
22c90 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
22ca0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
22cb0 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
22cc0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
22cd0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
22ce0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
22cf0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
22d00 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
22d10 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
22d20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
22d30 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
22d40 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
22d50 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
22d60 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
22d70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
22d80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
22d90 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
22da0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
22db0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
22dc0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
22dd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
22de0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
22df0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
22e00 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
22e10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
22e20 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f LL <td> BLO
22e30 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 B <td> Result
22e40 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
22e50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
22e60 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 EGER <td> FLOA
22e70 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 T <td> Conver
22e80 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 t from integer t
22e90 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c o float.** <tr><
22ea0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
22eb0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
22ec0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
22ed0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a of the integer.
22ee0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
22ef0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 GER <td> BLOB
22f00 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 <td> Same as
22f10 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a INTEGER->TEXT.*
22f20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
22f30 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 T <td> INTEGER
22f40 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
22f50 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e from float to in
22f60 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
22f70 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
22f80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
22f90 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
22fa0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
22fb0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
22fc0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
22fd0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f <td> Same as FLO
22fe0 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e AT->TEXT.** <tr>
22ff0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
23000 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
23010 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 > Use atoi().**
23020 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
23030 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
23040 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 <td> Use atof()
23050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
23060 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
23070 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
23080 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
23090 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
230a0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
230b0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
230c0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 n use atoi().**
230d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
230e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
230f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
23100 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
23110 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
23120 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
23130 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
23140 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
23150 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
23160 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
23170 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
23180 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 .** The table ab
23190 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 ove makes refere
231a0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 nce to standard
231b0 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 C library functi
231c0 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e ons atoi().** an
231d0 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 d atof(). SQLit
231e0 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c e does not reall
231f0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 y use these func
23200 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 tions. It has i
23210 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 ts.** own equiva
23220 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f lent internal ro
23230 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f utines. The ato
23240 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e i() and atof() n
23250 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 ames are.** used
23260 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f in the table fo
23270 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 r brevity and be
23280 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 cause they are f
23290 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a amiliar to most.
232a0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 ** C programmers
232b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
232c0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e at when type con
232d0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 versions occur,
232e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
232f0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 d by prior.** ca
23300 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
23310 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 olumn_blob(), sq
23320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23330 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 t(), and/or.** s
23340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23350 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e xt16() may be in
23360 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 validated..** ^(
23370 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
23380 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
23390 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
233a0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
233b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
233c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
233d0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
233e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
233f0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
23400 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
23410 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
23420 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
23430 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 is called. A ze
23440 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 ro-terminator mi
23450 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 ght.** need
23460 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
23470 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e the string.</li>
23480 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
23490 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
234a0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 UTF-8 text and s
234b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
234c0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 tes16() or.**
234d0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
234e0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
234f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
23500 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
23510 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
23520 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-16.</li>.**
23530 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
23540 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
23550 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 16 text and sqli
23560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
23570 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
23580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23590 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
235a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
235b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
235c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c to UTF-8.<
235d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a /li>.** </ul>)^.
235e0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f **.** ^Conversio
235f0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
23600 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
23610 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
23620 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
23630 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
23640 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
23650 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
23660 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
23670 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
23680 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
23690 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 pointer points
236a0 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 to will have bee
236b0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
236c0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
236d0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
236e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
236f0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
23700 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 but sometimes t
23710 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 hey.** are not p
23720 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 ossible and in t
23730 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 hose cases prior
23740 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e pointers are in
23750 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a validated..**.**
23760 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61 6e ^(The safest an
23770 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d d easiest to rem
23780 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 ember policy is
23790 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
237a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
237b0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
237c0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
237d0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
237e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
237f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
23800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
23810 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
23820 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
23830 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
23840 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
23850 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
23860 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
23870 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
23880 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
23890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
238a0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
238b0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f ul>)^.**.** In o
238c0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 ther words, you
238d0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 should call sqli
238e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
238f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f ),.** sqlite3_co
23900 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 lumn_blob(), or
23910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
23920 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f ext16() first to
23930 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c force the resul
23940 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 t.** into the de
23950 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 sired format, th
23960 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 en invoke sqlite
23970 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
23980 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
23990 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
239a0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 to find the size
239b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 of the result.
239c0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c Do not mix call
239d0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
239e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
239f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
23a00 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c blob() with call
23a10 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
23a20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
23a30 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 , and do not mix
23a40 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
23a50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
23a60 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 ).** with calls
23a70 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
23a80 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a n_bytes()..**.**
23a90 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 ^The pointers r
23aa0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
23ab0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
23ac0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
23ad0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
23ae0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
23af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23b00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
23b10 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
23b20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
23b30 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 ] is called. ^T
23b40 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
23b50 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
23b60 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
23b70 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
23b80 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
23b90 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
23ba0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
23bb0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
23bc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
23bd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
23be0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
23bf0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
23c00 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ree()]..**.** ^(
23c10 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
23c20 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
23c30 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 urs during the e
23c40 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 valuation of any
23c50 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 .** of these rou
23c60 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 tines, a default
23c70 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
23c80 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
23c90 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 value.** is eit
23ca0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 her the integer
23cb0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 0, the floating
23cc0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 point number 0.0
23cd0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 , or a NULL.** p
23ce0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 ointer. Subsequ
23cf0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
23d00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
23d10 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
23d20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 [SQLITE_NOMEM].)
23d30 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ^.*/.const void
23d40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23d50 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
23d60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
23d70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
23d80 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f n_bytes(sqlite3_
23d90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
23da0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
23db0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c lumn_bytes16(sql
23dc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23dd0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 iCol);.double sq
23de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
23df0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
23e00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
23e10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
23e20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
23e30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
23e40 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
23e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
23e60 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
23e70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 int iCol);.cons
23e80 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
23e90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23ea0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
23eb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 t*, int iCol);.c
23ec0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
23ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
23ee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23ef0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
23f00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
23f10 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
23f20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c , int iCol);.sql
23f30 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 ite3_value *sqli
23f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
23f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
23f60 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a int iCol);../*.*
23f70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 * CAPI3REF: Dest
23f80 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 roy A Prepared S
23f90 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
23fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
23fb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
23fc0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
23fd0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
23fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23ff0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 ]..** ^If the st
24000 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 atement was exec
24010 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c uted successfull
24020 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 y or not execute
24030 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a d at all, then.*
24040 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 * SQLITE_OK is r
24050 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 eturned. ^If exe
24060 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 cution of the st
24070 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 atement failed t
24080 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 hen an.** [error
24090 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
240a0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
240b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
240c0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
240d0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
240e0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 t any point duri
240f0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
24100 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 of the.** [prep
24110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
24120 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75 61 ^If the virtua
24130 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f l machine has no
24140 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 t.** completed e
24150 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
24160 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
24170 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
24180 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
24190 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
241a0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 n [sqlite3_inter
241b0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 rupt | interrupt
241c0 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 ]..** ^Incomplet
241d0 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 e updates may be
241e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 rolled back and
241f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 transactions ca
24200 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e nceled,.** depen
24210 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 ding on the circ
24220 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 umstances, and t
24230 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 he.** [error cod
24240 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c e] returned will
24250 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 be [SQLITE_ABOR
24260 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 T]..*/.int sqlit
24270 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 e3_finalize(sqli
24280 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
24290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
242a0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 F: Reset A Prepa
242b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
242c0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ject.**.** The s
242d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 qlite3_reset() f
242e0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
242f0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 d to reset a [pr
24300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24310 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b ].** object back
24320 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
24330 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 state, ready to
24340 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a be re-executed..
24350 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 ** ^Any SQL stat
24360 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 ement variables
24370 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 that had values
24380 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 bound to them us
24390 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ing.** the [sqli
243a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
243b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
243c0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 API] retain the
243d0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 ir values..** Us
243e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 e [sqlite3_clear
243f0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 _bindings()] to
24400 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e reset the bindin
24410 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b gs..**.** ^The [
24420 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
24430 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 ] interface rese
24440 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 ts the [prepared
24450 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a statement] S.**
24460 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 back to the beg
24470 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 inning of its pr
24480 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ogram..**.** ^If
24490 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
244a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
244b0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
244c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
244d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 statement] S ret
244e0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
244f0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f W] or [SQLITE_DO
24500 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 NE],.** or if [s
24510 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
24520 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 has never before
24530 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
24540 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 S,.** then [sqli
24550 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
24560 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
24570 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
24580 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
24590 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
245a0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
245b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
245c0 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 ement] S indicat
245d0 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 ed an error, the
245e0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 n.** [sqlite3_re
245f0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
24600 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
24610 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
24620 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
24630 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
24640 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 face does not ch
24650 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a ange the values.
24660 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 ** of any [sqlit
24670 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e e3_bind_blob|bin
24680 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 dings] on the [p
24690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
246a0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c t] S..*/.int sql
246b0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 ite3_reset(sqlit
246c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
246d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
246e0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 : Create Or Rede
246f0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f fine SQL Functio
24700 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ns.** KEYWORDS:
24710 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 {function creati
24720 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 on routines}.**
24730 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
24740 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
24750 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 QL function}.**
24760 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
24770 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
24780 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a QL functions}.**
24790 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66 .** ^These two f
247a0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 unctions (collec
247b0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 tively known as
247c0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 "function creati
247d0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a on routines").**
247e0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 are used to add
247f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
24800 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 r aggregates or
24810 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 to redefine the
24820 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 behavior.** of e
24830 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 xisting SQL func
24840 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
24850 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 tes. The only d
24860 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 ifference betwee
24870 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 n the.** two is
24880 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
24890 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e parameter, the n
248a0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c ame of the (scal
248b0 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a ar) function or.
248c0 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 ** aggregate, is
248d0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d encoded in UTF-
248e0 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 8 for sqlite3_cr
248f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 eate_function()
24900 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f and UTF-16.** fo
24910 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
24920 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a _function16()..*
24930 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
24940 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
24950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
24960 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 ction] to which
24970 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 the SQL.** funct
24980 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 ion is to be add
24990 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c ed. ^If an appl
249a0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 ication uses mor
249b0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 e than one datab
249c0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
249d0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 n then applicati
249e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
249f0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 unctions must be
24a00 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 added.** to eac
24a10 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
24a20 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 ction separately
24a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
24a40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
24a50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
24a60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
24a70 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
24a80 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
24a90 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
24aa0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
24ab0 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 to 255 bytes, ex
24ac0 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 clusive of.** th
24ad0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
24ae0 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 r. Note that th
24af0 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 e name length li
24b00 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c mit is in bytes,
24b10 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 not.** characte
24b20 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 rs. ^Any attemp
24b30 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 t to create a fu
24b40 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f nction with a lo
24b50 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c nger name.** wil
24b60 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c l result in [SQL
24b70 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 ITE_ERROR] being
24b80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
24b90 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
24ba0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
24bb0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
24bc0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
24bd0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
24be0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
24bf0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
24c00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
24c10 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
24c20 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
24c30 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
24c40 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
24c50 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
24c60 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
24c70 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
24c80 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
24c90 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
24ca0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
24cb0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
24cc0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
24cd0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
24ce0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
24cf0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
24d00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
24d10 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
24d20 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
24d30 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a specifies what.
24d40 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
24d50 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d | text encoding]
24d60 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 this SQL functi
24d70 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a on prefers for.*
24d80 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 * its parameters
24d90 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 . Any SQL funct
24da0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
24db0 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c on should be abl
24dc0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 e to work.** wor
24dd0 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 k with UTF-8, UT
24de0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
24df0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
24e00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
24e10 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
24e20 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
24e30 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
24e40 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 nother. ^An app
24e50 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
24e60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
24e70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
24e80 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
24e90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
24ea0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
24eb0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
24ec0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
24ed0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
24ee0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
24ef0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
24f00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
24f10 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
24f20 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
24f30 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
24f40 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
24f50 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
24f60 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
24f70 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
24f80 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
24f90 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
24fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
24fb0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
24fc0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
24fd0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
24fe0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
24ff0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
25000 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
25010 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 NY]..**.** ^(The
25020 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
25030 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
25040 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
25050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
25060 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
25070 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
25080 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
25090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
250a0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a user_data()].)^.
250b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 **.** The sevent
250c0 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 h, eighth and ni
250d0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 nth parameters,
250e0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
250f0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
25100 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
25110 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
25120 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
25130 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
25140 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
25150 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 . ^A scalar SQL
25160 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
25170 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
25180 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 ion of the xFunc
25190 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c .** callback onl
251a0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 y; NULL pointers
251b0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 should be passe
251c0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 d as the xStep a
251d0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 nd xFinal.** par
251e0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 ameters. ^An agg
251f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
25200 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
25210 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
25220 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
25230 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 Final and NULL s
25240 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 hould be passed
25250 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 for xFunc. ^To d
25260 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e elete an existin
25270 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f g.** SQL functio
25280 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
25290 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c pass NULL for al
252a0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
252b0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a callbacks..**.*
252c0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 * ^It is permitt
252d0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d ed to register m
252e0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
252f0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
25300 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ame.** functions
25310 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
25320 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 ame but with eit
25330 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 her differing nu
25340 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 mbers of.** argu
25350 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 ments or differi
25360 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 ng preferred tex
25370 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 t encodings. ^S
25380 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
25390 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
253a0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 tion that most c
253b0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 losely matches t
253c0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
253d0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 the.** SQL funct
253e0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 ion is used. ^A
253f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
25400 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 entation with a
25410 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 non-negative.**
25420 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 nArg parameter i
25430 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 s a better match
25440 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
25450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
25460 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 with.** a negati
25470 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e ve nArg. ^A fun
25480 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
25490 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
254a0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
254b0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
254c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
254d0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
254e0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
254f0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
25500 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
25510 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 .** ^A function
25520 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
25530 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
25540 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
25550 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
25560 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
25570 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
25580 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
25590 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
255a0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
255b0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
255c0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 .** ^Built-in fu
255d0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
255e0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
255f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
25600 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
25610 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 70 ** ^The first ap
25620 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25630 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 d function with
25640 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 a given name ove
25650 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 rrides all.** bu
25660 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
25670 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 in the same [da
25680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25690 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 n] with the same
256a0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 name..** ^Subse
256b0 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f quent applicatio
256c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
256d0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
256e0 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 name only overri
256f0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 de .** prior app
25700 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
25710 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
25720 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 are an exact mat
25730 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 ch for the.** nu
25740 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
25750 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 rs and preferred
25760 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
25770 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
25780 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
25790 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
257a0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
257b0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
257c0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
257d0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
257e0 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
257f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25800 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
25810 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
25820 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
25830 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
25840 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
25850 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ng..*/.int sqlit
25860 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
25870 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
25880 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
25890 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
258a0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
258b0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
258c0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
258d0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
258e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
258f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
25900 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
25910 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
25920 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
25930 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
25940 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
25950 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
25960 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
25970 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 _function16(. s
25980 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
25990 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 nst void *zFunct
259a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
259b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
259c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
259d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
259e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
259f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
25a00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
25a10 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
25a20 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
25a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
25a40 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
25a50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
25a60 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t*).);../*.** CA
25a70 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
25a80 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
25a90 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
25aa0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
25ab0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
25ac0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
25ad0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
25ae0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
25af0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
25b00 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
25b10 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
25b20 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
25b30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
25b40 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
25b50 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
25b60 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 LITE_UTF16
25b70 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 4 /* Use
25b80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
25b90 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
25ba0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 ITE_ANY
25bb0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
25bc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
25bd0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 on only */.#defi
25be0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
25bf0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
25c00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
25c10 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
25c20 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
25c30 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 F: Deprecated Fu
25c40 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 nctions.** DEPRE
25c50 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 CATED.**.** Thes
25c60 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
25c70 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 [deprecated]. I
25c80 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 n order to maint
25c90 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ain.** backwards
25ca0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 compatibility w
25cb0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 ith older code,
25cc0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
25cd0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 continue .** to
25ce0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 be supported. H
25cf0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c owever, new appl
25d00 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
25d10 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 avoid.** the use
25d20 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
25d30 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e ons. To help en
25d40 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 courage people t
25d50 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 o avoid.** using
25d60 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
25d70 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 , we are not goi
25d80 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 ng to tell you w
25d90 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a hat they do..*/.
25da0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f #ifndef SQLITE_O
25db0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 MIT_DEPRECATED.S
25dc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
25dd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 int sqlite3_agg
25de0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c regate_count(sql
25df0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
25e00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
25e10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 D int sqlite3_ex
25e20 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 pired(sqlite3_st
25e30 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 mt*);.SQLITE_DEP
25e40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
25e50 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e te3_transfer_bin
25e60 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
25e70 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d mt*, sqlite3_stm
25e80 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
25e90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
25ea0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
25eb0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f r(void);.SQLITE_
25ec0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
25ed0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 sqlite3_thread_c
25ee0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 leanup(void);.SQ
25ef0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
25f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
25f10 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
25f20 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
25f30 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c nt64,int),void*,
25f40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
25f50 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
25f60 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
25f70 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
25f80 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a arameter Values.
25f90 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
25fa0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
25fb0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
25fc0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
25fd0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
25fe0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
25ff0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
26000 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
26010 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
26020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
26030 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
26040 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
26050 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
26060 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
26070 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
26080 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
26090 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
260a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
260b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
260c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
260d0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
260e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
260f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
26100 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
26110 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d ** The 4th param
26120 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
26130 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
26140 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
26150 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 to.** [protected
26160 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
26170 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 objects. There
26180 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f is one [sqlite3_
26190 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f value] object fo
261a0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 r.** each parame
261b0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 ter to the SQL f
261c0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 unction. These
261d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
261e0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 d to.** extract
261f0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 values from the
26200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
26210 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 objects..**.** T
26220 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
26230 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 rk only with [pr
26240 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
26250 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
26260 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
26270 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 o use these rout
26280 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 ines on an [unpr
26290 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
262a0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
262b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
262c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
262d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
262e0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 tines work just
262f0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 like the corresp
26300 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 onding [column a
26310 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
26320 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
26330 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
26340 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 take a single [p
26350 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
26360 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a _value] object.*
26370 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 * pointer instea
26380 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f d of a [sqlite3_
26390 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 stmt*] pointer a
263a0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f nd an integer co
263b0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a lumn number..**.
263c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
263d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 value_text16() i
263e0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 nterface extract
263f0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
26400 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 g.** in the nati
26410 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 ve byte-order of
26420 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e the host machin
26430 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 e. ^The.** sqli
26440 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
26450 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 be() and sqlite3
26460 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
26470 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
26480 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 extract UTF-16 s
26490 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
264a0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
264b0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
264c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ely..**.** ^(The
264d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
264e0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e umeric_type() in
264f0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
26500 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d to apply.** num
26510 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f eric affinity to
26520 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 the value. Thi
26530 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 s means that an
26540 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 attempt is.** ma
26550 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 de to convert th
26560 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e e value to an in
26570 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e teger or floatin
26580 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 g point. If.**
26590 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f such a conversio
265a0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 n is possible wi
265b0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e thout loss of in
265c0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 formation (in ot
265d0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 her.** words, if
265e0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 the value is a
265f0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b string that look
26600 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 s like a number)
26610 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e .** then the con
26620 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f version is perfo
26630 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rmed. Otherwise
26640 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f no conversion o
26650 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 ccurs..** The [S
26660 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
26670 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 datatype] after
26680 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 conversion is re
26690 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 turned.)^.**.**
266a0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
266b0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
266c0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
266d0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
266e0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
266f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
26700 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
26710 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
26720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
26730 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
26740 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
26750 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
26760 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
26770 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
26780 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
26790 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
267a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
267b0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
267c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
267d0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
267e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
267f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
26800 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
26810 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
26820 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
26830 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
26840 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
26850 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 ters..*/.const v
26860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
26870 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f ue_blob(sqlite3_
26880 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
26890 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
268a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
268b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
268c0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 lue_bytes16(sqli
268d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 te3_value*);.dou
268e0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble sqlite3_valu
268f0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 e_double(sqlite3
26900 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
26910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
26920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
26930 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
26940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
26950 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
26960 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e *);.const unsign
26970 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
26980 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
26990 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
269a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
269b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 _value_text16(sq
269c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
269d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
269e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
269f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
26a00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
26a10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
26a20 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
26a30 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
26a40 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 e3_value_type(sq
26a50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
26a60 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
26a70 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
26a80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
26a90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26aa0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 Obtain Aggregate
26ab0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
26ac0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e t.**.** Implemen
26ad0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 tions of aggrega
26ae0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 te SQL functions
26af0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 use this.** rou
26b00 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
26b10 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 memory for stor
26b20 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
26b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
26b40 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
26b50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26b60 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
26b70 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 e is called .**
26b80 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
26b90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
26ba0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ion, SQLite.** a
26bb0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 llocates N of me
26bc0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 mory, zeroes out
26bd0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e that memory, an
26be0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
26bf0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 ter.** to the ne
26c00 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 w memory. ^On se
26c10 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
26c20 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
26c30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
26c40 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
26c50 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
26c60 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
26c70 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d ance,.** the sam
26c80 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 e buffer is retu
26c90 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 rned. Sqlite3_a
26ca0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
26cb0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a () is normally.*
26cc0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f * called once fo
26cd0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f r each invocatio
26ce0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 n of the xStep c
26cf0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e allback and then
26d00 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d one.** last tim
26d10 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 e when the xFina
26d20 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e l callback is in
26d30 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e voked. ^(When n
26d40 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 o rows match.**
26d50 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
26d60 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 ry, the xStep()
26d70 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
26d80 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
26d90 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 on.** implementa
26da0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 tion is never ca
26db0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 lled and xFinal(
26dc0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 ) is called exac
26dd0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 tly once..** In
26de0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c those cases, sql
26df0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
26e00 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 ontext() might b
26e10 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 e called for the
26e20 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 .** first time f
26e30 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 rom within xFina
26e40 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 l().)^.**.** ^Th
26e50 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
26e60 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
26e70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
26e80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
26e90 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 if N is.** less
26ea0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
26eb0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 zero or if a me
26ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 mory allocate er
26ed0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
26ee0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f * ^(The amount o
26ef0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 f space allocate
26f00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 d by sqlite3_agg
26f10 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
26f20 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d ,N) is.** determ
26f30 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 ined by the N pa
26f40 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 rameter on first
26f50 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
26f60 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a . Changing the.
26f70 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e ** value of N in
26f80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
26f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
26fa0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
26fb0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 within.** the sa
26fc0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
26fd0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 ction instance w
26fe0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 ill not resize t
26ff0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c he memory.** all
27000 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a ocation.)^.**.**
27010 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 ^SQLite automat
27020 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 ically frees the
27030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
27040 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d by .** sqlite3
27050 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
27060 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 xt() when the ag
27070 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f gregate query co
27080 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 ncludes..**.** T
27090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
270a0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 er must be a cop
270b0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c y of the.** [sql
270c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 ite3_context | S
270d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 QL function cont
270e0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 ext] that is the
270f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
27100 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 .** to the xStep
27110 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 or xFinal callb
27120 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 ack routine that
27130 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
27140 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e aggregate.** fun
27150 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
27160 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
27170 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
27180 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
27190 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 which.** the ag
271a0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
271b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
271c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
271d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
271e0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext(sqlite3_cont
271f0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 ext*, int nBytes
27200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
27210 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f EF: User Data Fo
27220 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a r Functions.**.*
27230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 * ^The sqlite3_u
27240 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 ser_data() inter
27250 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
27260 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
27270 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 inter that was t
27280 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 he pUserData par
27290 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 ameter (the 5th
272a0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
272b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
272c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
272d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
272e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
272f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
27300 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
27310 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
27320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
27330 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
27340 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
27350 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
27360 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
27370 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
27380 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
27390 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
273a0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
273b0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
273c0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 user_data(sqlite
273d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 3_context*);../*
273e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
273f0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
27400 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a n For Functions.
27410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27420 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
27430 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 ndle() interface
27440 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
27450 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 of.** the pointe
27460 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
27470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
27480 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
27490 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
274a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
274b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
274c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
274d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
274e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
274f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
27500 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
27510 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
27520 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 ction..*/.sqlite
27530 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 3 *sqlite3_conte
27540 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c xt_db_handle(sql
27550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
27560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27570 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 Function Auxili
27580 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 ary Data.**.** T
27590 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f he following two
275a0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 functions may b
275b0 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 e used by scalar
275c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
275d0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
275e0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
275f0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
27600 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
27610 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
27620 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
27630 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
27640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
27650 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
27660 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
27670 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
27680 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
27690 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
276a0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 preserved. This
276b0 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c may.** be used,
276c0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f for example, to
276d0 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 add a regular-e
276e0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 xpression matchi
276f0 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e ng scalar.** fun
27700 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 ction. The compi
27710 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 led version of t
27720 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
27730 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 ssion is stored
27740 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 as.** metadata a
27750 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
27760 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 he SQL value pas
27770 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c sed as the regul
27780 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a ar expression.**
27790 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 pattern. The c
277a0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 ompiled regular
277b0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 expression can b
277c0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 e reused on mult
277d0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 iple.** invocati
277e0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
277f0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 function so that
27800 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 the original pa
27810 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 ttern string.**
27820 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
27830 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f be recompiled o
27840 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f n each invocatio
27850 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 n..**.** ^The sq
27860 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
27870 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
27880 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
27890 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a to the metadata.
278a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 ** associated by
278b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
278c0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 _auxdata() funct
278d0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 ion with the Nth
278e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c argument.** val
278f0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ue to the applic
27900 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
27910 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d nction. ^If no m
27920 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e etadata has been
27930 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 ever.** been se
27940 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 t for the Nth ar
27950 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 gument of the fu
27960 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 nction, or if th
27970 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
27980 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ** function para
27990 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 meter has change
279a0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 d since the meta
279b0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a -data was set,.*
279c0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 * then sqlite3_g
279d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 et_auxdata() ret
279e0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
279f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
27a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
27a10 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
27a20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
27a30 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
27a40 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
27a50 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
27a60 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
27a70 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
27a80 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
27a90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
27aa0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
27ab0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
27ac0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
27ad0 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
27ae0 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
27af0 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
27b00 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 destroyed..** ^I
27b10 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c f it is not NULL
27b20 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e , SQLite will in
27b30 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 voke the destruc
27b40 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 tor.** function
27b50 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 given by the 4th
27b60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
27b70 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
27b80 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 a() on.** the me
27b90 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 tadata when the
27ba0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 corresponding fu
27bb0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 nction parameter
27bc0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 changes.** or w
27bd0 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 hen the SQL stat
27be0 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c ement completes,
27bf0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
27c00 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 first..**.** SQ
27c10 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 Lite is free to
27c20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 call the destruc
27c30 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 tor and drop met
27c40 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 adata on any.**
27c50 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 parameter of any
27c60 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 function at any
27c70 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c time. ^The onl
27c80 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 y guarantee is t
27c90 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 hat.** the destr
27ca0 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 uctor will be ca
27cb0 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 lled before the
27cc0 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 metadata is drop
27cd0 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 ped..**.** ^(In
27ce0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 practice, metada
27cf0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 ta is preserved
27d00 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e between function
27d10 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 calls for.** ex
27d20 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 pressions that a
27d30 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 re constant at c
27d40 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 ompile time. Thi
27d50 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 s includes liter
27d60 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 al.** values and
27d70 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e [parameters].)^
27d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
27d90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
27da0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
27db0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
27dc0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 ch.** the SQL fu
27dd0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
27de0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 g..*/.void *sqli
27df0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
27e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27e10 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 , int N);.void s
27e20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
27e30 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
27e40 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 xt*, int N, void
27e50 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
27e60 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *));.../*.** CAP
27e70 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 I3REF: Constants
27e80 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 Defining Specia
27e90 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 l Destructor Beh
27ea0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 avior.**.** Thes
27eb0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
27ec0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 lues for the des
27ed0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 tructor that is
27ee0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
27ef0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 .** final argume
27f00 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c nt to routines l
27f10 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ike [sqlite3_res
27f20 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 ult_blob()]. ^I
27f30 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 f the destructor
27f40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
27f50 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 SQLITE_STATIC, i
27f60 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
27f70 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 content pointer
27f80 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 is constant.**
27f90 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 and will never c
27fa0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 hange. It does
27fb0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 not need to be d
27fc0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a estroyed. ^The.
27fd0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ** SQLITE_TRANSI
27fe0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 ENT value means
27ff0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
28000 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 will likely cha
28010 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 nge in.** the ne
28020 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 ar future and th
28030 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 at SQLite should
28040 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 make its own pr
28050 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a ivate copy of.**
28060 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 the content bef
28070 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a ore returning..*
28080 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 *.** The typedef
28090 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f is necessary to
280a0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f work around pro
280b0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e blems in certain
280c0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 .** C++ compiler
280d0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 s. See ticket #
280e0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 2191..*/.typedef
280f0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f void (*sqlite3_
28100 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
28110 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 (void*);.#define
28120 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 SQLITE_STATIC
28130 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 ((sqlite3_de
28140 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 structor_type)0)
28150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
28160 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 TRANSIENT ((sq
28170 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
28180 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a _type)-1)../*.**
28190 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 CAPI3REF: Setti
281a0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 ng The Result Of
281b0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e An SQL Function
281c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
281d0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 tines are used b
281e0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 y the xFunc or x
281f0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 Final callbacks
28200 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e that.** implemen
28210 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
28220 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 and aggregates.
28230 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 See.** [sqlite3
28240 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
28250 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
28260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
28270 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 16()].** for add
28280 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
28290 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion..**.** These
282a0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 functions work
282b0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 very much like t
282c0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 he [parameter bi
282d0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 nding] family of
282e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 .** functions us
282f0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ed to bind value
28300 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
28310 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
28320 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
28330 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 Refer to the [SQ
28340 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 L parameter] doc
28350 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
28360 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
28370 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
28380 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28390 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 _blob() interfac
283a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
283b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
283c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
283d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
283e0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 the BLOB whose c
283f0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 ontent is pointe
28400 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 d.** to by the s
28410 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
28420 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 and which is N b
28430 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 ytes long where
28440 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 N is the.** thir
28450 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
28460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28470 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
28480 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 ) interfaces set
28490 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a the result of.*
284a0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
284b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
284c0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 on to be a BLOB
284d0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a containing all z
284e0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 ero.** bytes and
284f0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
28500 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
28510 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e value of the 2n
28520 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
28530 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28540 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 result_double()
28550 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
28560 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
28570 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
28580 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
28590 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 n to be a floati
285a0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 ng point value s
285b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 pecified.** by i
285c0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e ts 2nd argument.
285d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
285e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
285f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
28600 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
28610 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
28620 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
28630 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
28640 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
28650 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 ption..** ^SQLit
28660 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
28670 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
28680 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
28690 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
286a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
286b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
286c0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
286d0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
286e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
286f0 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 ^SQLite interpre
28700 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 ts the error.**
28710 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 message string f
28720 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
28730 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 lt_error() as UT
28740 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 F-8. ^SQLite.**
28750 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 interprets the s
28760 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
28770 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
28780 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 6() as UTF-16 in
28790 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 native.** byte
287a0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 order. ^If the
287b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
287c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
287d0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
287e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
287f0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 rror16() is nega
28800 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
28810 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 takes as the er
28820 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 ror.** message a
28830 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 ll text up throu
28840 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
28850 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
28860 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
28870 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
28880 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
28890 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
288a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
288b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
288c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
288d0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 es that many.**
288e0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
288f0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 cters) from the
28900 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 2nd parameter as
28910 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
28920 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ge..** ^The sqli
28930 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
28940 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
28950 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
28960 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
28970 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
28980 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
28990 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
289a0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
289b0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
289c0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
289d0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
289e0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
289f0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
28a00 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
28a10 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 m..** ^The sqlit
28a20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
28a30 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 code() function
28a40 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f changes the erro
28a50 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e r code.** return
28a60 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 ed by SQLite as
28a70 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 a result of an e
28a80 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 rror in a functi
28a90 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 on. ^By default
28aa0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
28ab0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
28ac0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 ROR. ^A subsequ
28ad0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
28ae0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
28af0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
28b00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
28b10 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 ) resets the err
28b20 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 or code to SQLIT
28b30 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e E_ERROR..**.** ^
28b40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
28b50 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 lt_toobig() inte
28b60 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
28b70 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
28b80 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
28b90 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
28ba0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f g or BLOB is too
28bb0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 long to represe
28bc0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
28bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f qlite3_result_no
28be0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 mem() interface
28bf0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
28c00 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
28c10 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
28c20 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
28c30 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a cation failed..*
28c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
28c50 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
28c60 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
28c70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
28c80 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
28c90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
28ca0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
28cb0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
28cc0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
28cd0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
28ce0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
28cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28d00 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 _int64() interfa
28d10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
28d20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
28d30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
28d40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
28d50 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
28d60 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
28d70 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
28d80 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
28d90 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
28da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
28db0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ll() interface s
28dc0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
28dd0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
28de0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
28df0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
28e00 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 e NULL..**.** ^T
28e10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28e20 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 t_text(), sqlite
28e30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
28e40 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 ),.** sqlite3_re
28e50 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c sult_text16le(),
28e60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
28e70 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 ult_text16be() i
28e80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 nterfaces.** set
28e90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
28ea0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 e of the applica
28eb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
28ec0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 ction to be.** a
28ed0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 text string whi
28ee0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 ch is represente
28ef0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d d as UTF-8, UTF-
28f00 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
28f10 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 rder,.** UTF-16
28f20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f little endian, o
28f30 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 r UTF-16 big end
28f40 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
28f50 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 y..** ^SQLite ta
28f60 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 kes the text res
28f70 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 ult from the app
28f80 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a lication from.**
28f90 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
28fa0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 er of the sqlite
28fb0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
28fc0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 nterfaces..** ^I
28fd0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
28fe0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
28ff0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
29000 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
29010 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
29020 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 SQLite takes res
29030 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 ult text from th
29040 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a e 2nd parameter.
29050 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 ** through the f
29060 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
29070 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
29080 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
29090 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
290a0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
290b0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e aces.** is non-n
290c0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 egative, then as
290d0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 many bytes (not
290e0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 characters) of
290f0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e the text.** poin
29100 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e ted to by the 2n
29110 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 d parameter are
29120 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 taken as the app
29130 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
29140 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 .** function res
29150 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ult..** ^If the
29160 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
29170 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
29180 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
29190 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
291a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
291b0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 s a non-NULL poi
291c0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
291d0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 e calls that.**
291e0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 function as the
291f0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
29200 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
29210 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 esult when it ha
29220 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 s.** finished us
29230 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
29240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
29250 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
29260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29270 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
29280 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 or to.** sqlite
29290 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
292a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
292b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 stant SQLITE_STA
292c0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 TIC, then SQLite
292d0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
292e0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
292f0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 B result is in c
29300 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e onstant space an
29310 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f d does not.** co
29320 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f py the content o
29330 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
29340 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 nor call a destr
29350 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e uctor on the con
29360 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 tent.** when it
29370 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
29380 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
29390 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
293a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
293b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
293c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
293d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
293e0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
293f0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
29400 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 t SQLITE_TRANSIE
29410 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 NT.** then SQLit
29420 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
29430 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 f the result int
29440 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 o space obtained
29450 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 from.** from [s
29460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
29470 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 before it retur
29480 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
29490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
294a0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 lue() interface
294b0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
294c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
294d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
294e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 nction to be a c
294f0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 opy the.** [unpr
29500 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
29510 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 value] object sp
29520 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 ecified by the 2
29530 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e nd parameter. ^
29540 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 The.** sqlite3_r
29550 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
29560 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
29570 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
29580 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 ite3_value].** s
29590 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 o that the [sqli
295a0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 te3_value] speci
295b0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 fied in the para
295c0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 meter may change
295d0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f or.** be deallo
295e0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 cated after sqli
295f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
29600 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f () returns witho
29610 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b ut harm..** ^A [
29620 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
29630 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
29640 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 may always be us
29650 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b ed where an.** [
29660 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
29670 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
29680 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 t is required, s
29690 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 o either.** kind
296a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
296b0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 ue] object can b
296c0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 e used with this
296d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
296e0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 * If these routi
296f0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 nes are called f
29700 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 rom within the d
29710 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a ifferent thread.
29720 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
29730 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
29740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
29750 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
29760 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 received.** the
29770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
29780 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
29790 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
297a0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 fined..*/.void s
297b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
297c0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
297d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
297e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
297f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
29800 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
29810 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
29820 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
29830 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29840 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
29850 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
29860 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
29870 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
29880 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
29890 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
298a0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
298b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
298c0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
298d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
298e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
298f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
29900 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
29910 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
29920 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
29930 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ode(sqlite3_cont
29940 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
29950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29960 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 int(sqlite3_cont
29970 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
29980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29990 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
299a0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
299b0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c int64);.void sql
299c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
299d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
299e0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
299f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c _result_text(sql
29a00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
29a10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c onst char*, int,
29a20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
29a30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
29a40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c esult_text16(sql
29a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
29a60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
29a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
29a80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
29a90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 esult_text16le(s
29aa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
29ab0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
29ac0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
29ad0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
29ae0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
29af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29b00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
29b10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
29b20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
29b30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 _result_value(sq
29b40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
29b60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
29b70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 sult_zeroblob(sq
29b80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29b90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
29ba0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 API3REF: Define
29bb0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 New Collating Se
29bc0 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 quences.**.** Th
29bd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
29be0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 e used to add ne
29bf0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 w collation sequ
29c00 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 ences to the.**
29c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
29c20 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
29c30 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
29c40 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
29c50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 e name of the ne
29c60 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 w collation sequ
29c70 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 ence is specifie
29c80 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 d as a UTF-8 str
29c90 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 ing.** for sqlit
29ca0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
29cb0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ion() and sqlite
29cc0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
29cd0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 on_v2().** and a
29ce0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 UTF-16 string f
29cf0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
29d00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
29d10 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a ^In all cases.*
29d20 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 * the name is pa
29d30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
29d40 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
29d50 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
29d60 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
29d70 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 may be one of th
29d80 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c e constants [SQL
29d90 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 ITE_UTF8],.** [S
29da0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 QLITE_UTF16LE],
29db0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
29dc0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 BE], indicating
29dd0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 that the user-su
29de0 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e pplied.** routin
29df0 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 e expects to be
29e00 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 passed pointers
29e10 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 to strings encod
29e20 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a ed using UTF-8,.
29e30 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
29e40 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d -endian, or UTF-
29e50 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 16 big-endian, r
29e60 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68 espectively. ^Th
29e70 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d e.** third argum
29e80 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 ent might also b
29e90 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d e [SQLITE_UTF16]
29ea0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
29eb0 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a t the routine.**
29ec0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
29ed0 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 s to be UTF-16 s
29ee0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 trings in the na
29ef0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
29f00 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d or the.** argum
29f10 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 ent can be [SQLI
29f20 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
29f30 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 ] if the.** the
29f40 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
29f50 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 pointers to 16-b
29f60 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 it word aligned
29f70 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 strings.** of UT
29f80 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
29f90 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
29fa0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 *.** A pointer t
29fb0 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c o the user suppl
29fc0 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 ied routine must
29fd0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
29fe0 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d e fifth.** argum
29ff0 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20 ent. ^If it is
2a000 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 NULL, this is th
2a010 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 e same as deleti
2a020 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e ng the collation
2a030 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f .** sequence (so
2a040 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
2a050 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d not call it anym
2a060 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 ore)..** ^Each t
2a070 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 ime the applicat
2a080 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e ion supplied fun
2a090 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
2a0a0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a , it is passed.*
2a0b0 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 * as its first p
2a0c0 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 arameter a copy
2a0d0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 of the void* pas
2a0e0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 sed as the fourt
2a0f0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f h argument.** to
2a100 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2a110 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 collation() or s
2a120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a130 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a llation16()..**.
2a140 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e ** ^The remainin
2a150 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 g arguments to t
2a160 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 he application-s
2a170 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 upplied routine
2a180 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c are two strings,
2a190 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 .** each represe
2a1a0 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 nted by a (lengt
2a1b0 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e h, data) pair an
2a1c0 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 d encoded in the
2a1d0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 encoding.** tha
2a1e0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 t was passed as
2a1f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
2a200 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c nt when the coll
2a210 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 ation sequence w
2a220 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 as.** registered
2a230 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
2a240 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 on defined colla
2a250 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f tion routine sho
2a260 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 uld.** return ne
2a270 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 gative, zero or
2a280 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20 positive if the
2a290 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
2a2a0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 less than,.** eq
2a2b0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 ual to, or great
2a2c0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f er than the seco
2a2d0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 nd string. i.e.
2a2e0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e (STRING1 - STRIN
2a2f0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 G2)..**.** ^The
2a300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2a310 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f ollation_v2() wo
2a320 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
2a330 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2a340 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
2a350 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 at it takes an e
2a360 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 xtra argument wh
2a370 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 ich is a destruc
2a380 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 tor for.** the c
2a390 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 ollation. ^The
2a3a0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
2a3b0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f lled when the co
2a3c0 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 llation is.** de
2a3d0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 stroyed and is p
2a3e0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 assed a copy of
2a3f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2a400 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 eter void* point
2a410 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c er.** of the sql
2a420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a430 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e ation_v2()..** ^
2a440 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 Collations are d
2a450 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 estroyed when th
2a460 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
2a470 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 n by later calls
2a480 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 to the.** colla
2a490 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
2a4a0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
2a4b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2a4c0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f nnection] is clo
2a4d0 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 sed.** using [sq
2a4e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
2a4f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2a500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
2a510 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e ion_needed()] an
2a520 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 d [sqlite3_colla
2a530 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d tion_needed16()]
2a540 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2a550 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2a560 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a n(. sqlite3*, .
2a570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
2a580 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
2a590 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
2a5a0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
2a5b0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
2a5c0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
2a5d0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 void*).);.int s
2a5e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a5f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
2a600 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2a610 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
2a620 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
2a630 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
2a640 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
2a650 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
2a660 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
2a670 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
2a680 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e oy)(void*).);.in
2a690 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2a6a0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 _collation16(.
2a6b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
2a6c0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a st void *zName,.
2a6d0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
2a6e0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
2a6f0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
2a700 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
2a710 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
2a720 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
2a730 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 3REF: Collation
2a740 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 Needed Callbacks
2a750 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 .**.** ^To avoid
2a760 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 having to regis
2a770 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f ter all collatio
2a780 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f n sequences befo
2a790 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a re a database.**
2a7a0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 can be used, a
2a7b0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 single callback
2a7c0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 function may be
2a7d0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
2a7e0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
2a7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
2a800 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2a810 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
2a820 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
2a830 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 quence is requir
2a840 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
2a850 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 e function is re
2a860 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 gistered using t
2a870 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 he sqlite3_colla
2a880 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 tion_needed() AP
2a890 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 I,.** then it is
2a8a0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 passed the name
2a8b0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 s of undefined c
2a8c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2a8d0 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a es as strings.**
2a8e0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d encoded in UTF-
2a8f0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 8. ^If sqlite3_c
2a900 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
2a910 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 6() is used,.**
2a920 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 the names are pa
2a930 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 ssed as UTF-16 i
2a940 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 n machine native
2a950 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
2a960 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 ^A call to eithe
2a970 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 r function repla
2a980 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 ces the existing
2a990 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 collation-neede
2a9a0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a d callback..**.*
2a9b0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c * ^(When the cal
2a9c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
2a9d0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 , the first argu
2a9e0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 ment passed is a
2a9f0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 copy.** of the
2aa00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
2aa10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 to sqlite3_colla
2aa20 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 tion_needed() or
2aa30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c .** sqlite3_coll
2aa40 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
2aa50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
2aa60 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 gument is the da
2aa70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
2aa80 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 tion. The third
2aa90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
2aaa0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
2aab0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
2aac0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 BE],.** or [SQLI
2aad0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 TE_UTF16LE], ind
2aae0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 icating the most
2aaf0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 desirable form
2ab00 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
2ab10 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e .** sequence fun
2ab20 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 ction required.
2ab30 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
2ab40 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
2ab50 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 e of the.** requ
2ab60 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ired collation s
2ab70 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a equence.)^.**.**
2ab80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
2ab90 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 nction should re
2aba0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 gister the desir
2abb0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 ed collation usi
2abc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
2abd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
2abe0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
2abf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
2ac00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
2ac10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2ac20 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e ion_v2()]..*/.in
2ac30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
2ac40 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
2ac50 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
2ac60 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
2ac70 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
2ac80 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
2ac90 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c har*).);.int sql
2aca0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2acb0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 eeded16(. sqlit
2acc0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 e3*, . void*,.
2acd0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
2ace0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
2acf0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a tRep,const void*
2ad00 29 0a 29 3b 0a 0a 23 69 66 20 53 51 4c 49 54 45 ).);..#if SQLITE
2ad10 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a _HAS_CODEC./*.**
2ad20 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 Specify the key
2ad30 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 for an encrypte
2ad40 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 d database. Thi
2ad50 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 s routine should
2ad60 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 be.** called ri
2ad70 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 ght after sqlite
2ad80 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_open()..**.**
2ad90 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
2ada0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
2adb0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
2adc0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
2add0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
2ade0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
2adf0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
2ae00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2ae10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2ae20 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
2ae30 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
2ae40 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
2ae50 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
2ae60 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
2ae70 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
2ae80 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
2ae90 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
2aea0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
2aeb0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
2aec0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
2aed0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
2aee0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
2aef0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
2af00 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
2af10 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
2af20 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
2af30 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
2af40 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
2af50 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
2af60 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
2af70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2af80 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
2af90 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2afa0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2afb0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
2afc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2afd0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
2afe0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
2aff0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
2b000 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 Specify the acti
2b010 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 vation key for a
2b020 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 SEE database.
2b030 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 Unless .** activ
2b040 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 ated, none of th
2b050 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 e SEE routines w
2b060 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 ill work..*/.voi
2b070 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 d sqlite3_activa
2b080 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 te_see(. const
2b090 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
2b0a0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
2b0b0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
2b0c0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 .);.#endif..#ifd
2b0d0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 ef SQLITE_ENABLE
2b0e0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 _CEROD./*.** Spe
2b0f0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 cify the activat
2b100 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 ion key for a CE
2b110 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 ROD database. U
2b120 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 nless .** activa
2b130 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 ted, none of the
2b140 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 CEROD routines
2b150 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f will work..*/.vo
2b160 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 id sqlite3_activ
2b170 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e ate_cerod(. con
2b180 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 st char *zPassPh
2b190 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 rase /* A
2b1a0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 ctivation phrase
2b1b0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f */.);.#endif../
2b1c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2b1d0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e uspend Execution
2b1e0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d For A Short Tim
2b1f0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
2b200 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e ite3_sleep() fun
2b210 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 ction causes the
2b220 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 current thread
2b230 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 to suspend execu
2b240 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c tion.** for at l
2b250 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 east a number of
2b260 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 milliseconds sp
2b270 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 ecified in its p
2b280 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2b290 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e ^If the operatin
2b2a0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f g system does no
2b2b0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 t support sleep
2b2c0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a requests with.**
2b2d0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d millisecond tim
2b2e0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 e resolution, th
2b2f0 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c en the time will
2b300 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 be rounded up t
2b310 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 o.** the nearest
2b320 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 second. ^The nu
2b330 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
2b340 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 onds of sleep ac
2b350 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 tually.** reques
2b360 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 ted from the ope
2b370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 rating system is
2b380 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2b390 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 ^SQLite impleme
2b3a0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 nts this interfa
2b3b0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 ce by calling th
2b3c0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 e xSleep().** me
2b3d0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
2b3e0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
2b3f0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 ] object..*/.int
2b400 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 sqlite3_sleep(i
2b410 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2b420 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 3REF: Name Of Th
2b430 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 e Folder Holding
2b440 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 Temporary Files
2b450 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 .**.** ^(If this
2b460 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
2b470 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
2b480 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 t to a string wh
2b490 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 ich is.** the na
2b4a0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 me of a folder (
2b4b0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 a.k.a. directory
2b4c0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 ), then all temp
2b4d0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 orary files.** c
2b4e0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 reated by SQLite
2b4f0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 when using a bu
2b500 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f ilt-in [sqlite3_
2b510 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 vfs | VFS].** wi
2b520 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 ll be placed in
2b530 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 that directory.)
2b540 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 ^ ^If this vari
2b550 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c able.** is a NUL
2b560 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
2b570 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 SQLite performs
2b580 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 a search for an
2b590 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 appropriate.** t
2b5a0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 emporary file di
2b5b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 rectory..**.** I
2b5c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
2b5d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 read or modify
2b5e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e this variable in
2b5f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a more than one.*
2b600 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 * thread at a ti
2b610 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 me. It is not s
2b620 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d afe to read or m
2b630 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 odify this varia
2b640 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 ble.** if a [dat
2b650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b660 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 ] is being used
2b670 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
2b680 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a in a separate.*
2b690 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 * thread..** It
2b6a0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 is intended that
2b6b0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 this variable b
2b6c0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 e set once.** as
2b6d0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 part of process
2b6e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
2b6f0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 and before any S
2b700 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a QLite interface.
2b710 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 ** routines have
2b720 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 been called and
2b730 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
2b740 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 ble remain uncha
2b750 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 nged.** thereaft
2b760 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b er..**.** ^The [
2b770 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
2b780 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 tory pragma] may
2b790 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
2b7a0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a iable and cause.
2b7b0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 ** it to point t
2b7c0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
2b7d0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2b7e0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 malloc]. ^Furth
2b7f0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b ermore,.** the [
2b800 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
2b810 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 tory pragma] alw
2b820 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 ays assumes that
2b830 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 any string.** t
2b840 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
2b850 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 e points to is h
2b860 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 eld in memory ob
2b870 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
2b880 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
2b890 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 and the pragma
2b8a0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 may attempt to f
2b8b0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a ree that memory.
2b8c0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
2b8d0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 3_free]..** Henc
2b8e0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 e, if this varia
2b8f0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 ble is modified
2b900 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 directly, either
2b910 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a it should be.**
2b920 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 made NULL or ma
2b930 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d de to point to m
2b940 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
2b950 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2b960 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 loc].** or else
2b970 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b the use of the [
2b980 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
2b990 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f tory pragma] sho
2b9a0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a uld be avoided..
2b9b0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e */.SQLITE_EXTERN
2b9c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 char *sqlite3_t
2b9d0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a emp_directory;..
2b9e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2b9f0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f Test For Auto-Co
2ba00 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 mmit Mode.** KEY
2ba10 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d WORDS: {autocomm
2ba20 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e it mode}.**.** ^
2ba30 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
2ba40 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 autocommit() int
2ba50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e erface returns n
2ba60 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 on-zero or.** ze
2ba70 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 ro if the given
2ba80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ba90 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 ion is or is not
2baa0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d in autocommit m
2bab0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 ode,.** respecti
2bac0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d vely. ^Autocomm
2bad0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 it mode is on by
2bae0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 default..** ^Au
2baf0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
2bb00 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
2bb10 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
2bb20 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 ..** ^Autocommit
2bb30 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 mode is re-enab
2bb40 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 led by a [COMMIT
2bb50 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e ] or [ROLLBACK].
2bb60 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 .**.** If certai
2bb70 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 n kinds of error
2bb80 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 s occur on a sta
2bb90 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 tement within a
2bba0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a multi-statement.
2bbb0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 ** transaction (
2bbc0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 errors including
2bbd0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 [SQLITE_FULL],
2bbe0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a [SQLITE_IOERR],.
2bbf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
2bc00 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ], [SQLITE_BUSY]
2bc10 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e , and [SQLITE_IN
2bc20 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 TERRUPT]) then t
2bc30 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f he.** transactio
2bc40 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 n might be rolle
2bc50 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
2bc60 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ally. The only
2bc70 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f way to.** find o
2bc80 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 ut whether SQLit
2bc90 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2bca0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 rolled back the
2bcb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 transaction afte
2bcc0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 r.** an error is
2bcd0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e to use this fun
2bce0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ction..**.** If
2bcf0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 another thread c
2bd00 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 hanges the autoc
2bd10 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 ommit status of
2bd20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
2bd30 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
2bd40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
2bd50 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 running, then t
2bd60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
2bd70 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
2bd80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2bd90 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 get_autocommit(s
2bda0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
2bdb0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
2bdc0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e The Database Han
2bdd0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 dle Of A Prepare
2bde0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
2bdf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
2be00 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 b_handle interfa
2be10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
2be20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2be30 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 ion] handle.** t
2be40 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 o which a [prepa
2be50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 red statement] b
2be60 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 elongs. ^The [d
2be70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2be80 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 on].** returned
2be90 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 by sqlite3_db_ha
2bea0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 ndle is the same
2beb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2bec0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 ction].** that w
2bed0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
2bee0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 ument.** to the
2bef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2bf00 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 _v2()] call (or
2bf10 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 its variants) th
2bf20 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a at was used to.*
2bf30 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 * create the sta
2bf40 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 tement in the fi
2bf50 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 rst place..*/.sq
2bf60 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 lite3 *sqlite3_d
2bf70 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
2bf80 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2bf90 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 CAPI3REF: Find t
2bfa0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
2bfb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a statement.**.**
2bfc0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
2bfd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2bfe0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b er to the next [
2bff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c000 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 nt] after.** pSt
2c010 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 mt associated wi
2c020 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
2c030 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 connection] pDb
2c040 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 . ^If pStmt is
2c050 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 NULL.** then thi
2c060 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
2c070 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2c080 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 the first prepa
2c090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
2c0a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2c0b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2c0c0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e nnection pDb. ^
2c0d0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
2c0e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
2c0f0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
2c100 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
2c110 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
2c120 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
2c130 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2c140 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
2c150 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
2c160 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2c170 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
2c180 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
2c190 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2c1a0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
2c1b0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
2c1c0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
2c1d0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f ter..*/.sqlite3_
2c1e0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 stmt *sqlite3_ne
2c1f0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 xt_stmt(sqlite3
2c200 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 *pDb, sqlite3_st
2c210 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2c220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
2c230 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b mit And Rollback
2c240 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 Notification Ca
2c250 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
2c260 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 he sqlite3_commi
2c270 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 t_hook() interfa
2c280 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
2c290 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
2c2a0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
2c2b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
2c2c0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d nsaction is [COM
2c2d0 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d MIT | committed]
2c2e0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 ..** ^Any callba
2c2f0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 ck set by a prev
2c300 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c ious call to sql
2c310 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
2c320 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 ().** for the sa
2c330 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
2c340 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
2c350 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 dden..** ^The sq
2c360 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2c370 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
2c380 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
2c390 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
2c3a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
2c3b0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
2c3c0 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 ction is [ROLLBA
2c3d0 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b CK | rolled back
2c3e0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 ]..** ^Any callb
2c3f0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
2c400 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
2c410 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2c420 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
2c430 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
2c440 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
2c450 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 rridden..** ^The
2c460 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 pArg argument i
2c470 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
2c480 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
2c490 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
2c4a0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 lback on a commi
2c4b0 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 t hook function
2c4c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2c4d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ,.** then the co
2c4e0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 mmit is converte
2c4f0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
2c500 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 k..**.** ^The sq
2c510 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
2c520 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c k(D,C,P) and sql
2c530 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
2c540 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 ok(D,C,P) functi
2c550 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 ons.** return th
2c560 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f e P argument fro
2c570 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 m the previous c
2c580 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 all of the same
2c590 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 function.** on t
2c5a0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
2c5b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c e connection] D,
2c5c0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 or NULL for.**
2c5d0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 the first call f
2c5e0 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e or each function
2c5f0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on D..**.** The
2c600 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d callback implem
2c610 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f entation must no
2c620 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
2c630 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
2c640 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
2c650 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
2c660 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 nvoked the callb
2c670 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e ack. Any action
2c680 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 s.** to modify t
2c690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2c6a0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 ection must be d
2c6b0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 eferred until af
2c6c0 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c ter the.** compl
2c6d0 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 etion of the [sq
2c6e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
2c6f0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
2c700 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 d the commit.**
2c710 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b or rollback hook
2c720 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c in the first pl
2c730 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ace..** Note tha
2c740 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
2c750 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
2c760 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
2c770 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
2c780 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
2c790 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
2c7a0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
2c7b0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
2c7c0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 graph..**.** ^Re
2c7d0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c gistering a NULL
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
2c7f0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e es the callback.
2c800 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 .**.** ^When the
2c810 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c commit hook cal
2c820 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
2c830 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 turns zero, the
2c840 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 [COMMIT].** oper
2c850 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 ation is allowed
2c860 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 to continue nor
2c870 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 mally. ^If the
2c880 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 commit hook.** r
2c890 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
2c8a0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 then the [COMMI
2c8b0 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 T] is converted
2c8c0 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b into a [ROLLBACK
2c8d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 ]..** ^The rollb
2c8e0 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f ack hook is invo
2c8f0 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 ked on a rollbac
2c900 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 k that results f
2c910 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 rom a commit.**
2c920 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e hook returning n
2c930 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 on-zero, just as
2c940 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 it would be wit
2c950 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c h any other roll
2c960 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 back..**.** ^For
2c970 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
2c980 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
2c990 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
2c9a0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
2c9b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
2c9c0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
2c9d0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
2c9e0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
2c9f0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
2ca00 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
2ca10 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
2ca20 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
2ca30 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 .** ^The rollbac
2ca40 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f k callback is no
2ca50 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 t invoked if a t
2ca60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a ransaction is.**
2ca70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
2ca80 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 olled back becau
2ca90 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
2caa0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
2cab0 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f osed..** ^The ro
2cac0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 llback callback
2cad0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
2cae0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
2caf0 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 is.** rolled bac
2cb00 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d k because a comm
2cb10 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 it callback retu
2cb20 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a rned non-zero..*
2cb30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
2cb40 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 e [sqlite3_updat
2cb50 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 e_hook()] interf
2cb60 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ace..*/.void *sq
2cb70 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
2cb80 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 k(sqlite3*, int(
2cb90 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
2cba0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
2cbb0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 _rollback_hook(s
2cbc0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 qlite3*, void(*)
2cbd0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 (void *), void*)
2cbe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2cbf0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e F: Data Change N
2cc00 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
2cc10 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
2cc20 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
2cc30 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
2cc40 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
2cc50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
2cc60 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
2cc70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2cc80 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
2cc90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2cca0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
2ccb0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
2ccc0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
2ccd0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
2cce0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 d..** ^Any callb
2ccf0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
2cd00 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
2cd10 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 is function.** f
2cd20 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2cd30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2cd40 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2cd50 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
2cd60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2cd70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 ointer to the fu
2cd80 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 nction to invoke
2cd90 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 when a.** row i
2cda0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
2cdb0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
2cdc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
2cdd0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
2cde0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
2cdf0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 of the third ar
2ce00 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
2ce10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2ce20 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f ()..** ^The seco
2ce30 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
2ce40 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
2ce50 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
2ce60 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
2ce70 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
2ce80 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
2ce90 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
2cea0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
2ceb0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
2cec0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
2ced0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 ^The third and
2cee0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
2cef0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
2cf00 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
2cf10 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
2cf20 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e base and table n
2cf30 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ame containing t
2cf40 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e he affected row.
2cf50 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 .** ^The final c
2cf60 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
2cf70 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
2cf80 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
2cf90 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 ^In the case of
2cfa0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 an update, this
2cfb0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 is the [rowid] a
2cfc0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 fter the update
2cfd0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a takes place..**.
2cfe0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 ** ^(The update
2cff0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f hook is not invo
2d000 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
2d010 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 l system tables
2d020 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 are.** modified
2d030 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 (i.e. sqlite_mas
2d040 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 ter and sqlite_s
2d050 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a equence).)^.**.*
2d060 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e * ^In the curren
2d070 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
2d080 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f , the update hoo
2d090 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f k.** is not invo
2d0a0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 ked when duplica
2d0b0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 tion rows are de
2d0c0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 leted because of
2d0d0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c an.** [ON CONFL
2d0e0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 ICT | ON CONFLIC
2d0f0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 T REPLACE] claus
2d100 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 e. ^Nor is the
2d110 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
2d120 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 nvoked when rows
2d130 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 are deleted usi
2d140 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 ng the [truncate
2d150 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a optimization]..
2d160 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e ** The exception
2d170 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 s defined in thi
2d180 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 s paragraph migh
2d190 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 t change in a fu
2d1a0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
2d1b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
2d1c0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
2d1d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2d1e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
2d1f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
2d200 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
2d210 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2d220 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
2d230 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 e update hook.
2d240 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
2d250 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
2d260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2d270 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
2d280 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
2d290 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
2d2a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
2d2b0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
2d2c0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
2d2d0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 update hook..**
2d2e0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
2d2f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2d300 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
2d310 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
2d320 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
2d330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
2d340 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
2d350 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
2d360 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
2d370 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2d380 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
2d390 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a C,P) function.**
2d3a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 returns the P a
2d3b0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
2d3c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a previous call.*
2d3d0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
2d3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2d3f0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
2d400 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
2d410 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a call on D..**.**
2d420 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
2d430 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2d440 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ok()] and [sqlit
2d450 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
2d460 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
2d470 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 s..*/.void *sqli
2d480 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
2d490 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2d4a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 void(*)(void *,i
2d4b0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a nt ,char const *
2d4c0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 ,char const *,sq
2d4d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 lite3_int64),.
2d4e0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*.);../*.**
2d4f0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
2d500 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 Or Disable Shar
2d510 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a ed Pager Cache.*
2d520 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 * KEYWORDS: {sha
2d530 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a red cache}.**.**
2d540 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
2d550 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
2d560 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 les the sharing
2d570 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
2d580 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 cache.** and sch
2d590 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 ema data structu
2d5a0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 res between [dat
2d5b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2d5c0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a | connections].
2d5d0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 ** to the same d
2d5e0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 atabase. Sharing
2d5f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
2d600 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 he argument is t
2d610 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 rue.** and disab
2d620 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
2d630 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a ent is false.)^.
2d640 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 **.** ^Cache sha
2d650 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 ring is enabled
2d660 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 and disabled for
2d670 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 an entire proce
2d680 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 ss..** This is a
2d690 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 change as of SQ
2d6a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
2d6b0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 .0. In prior ver
2d6c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c sions of SQLite,
2d6d0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 .** sharing was
2d6e0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
2d6f0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 led for each thr
2d700 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ead separately..
2d710 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 **.** ^(The cach
2d720 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 e sharing mode s
2d730 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 et by this inter
2d740 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c face effects all
2d750 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 subsequent.** c
2d760 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2d770 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2d780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 e3_open_v2()], a
2d790 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
2d7a0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 16()]..** Existi
2d7b0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ng database conn
2d7c0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 ections continue
2d7d0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 use the sharing
2d7e0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 mode.** that wa
2d7f0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 s in effect at t
2d800 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 he time they wer
2d810 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a e opened.)^.**.*
2d820 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
2d830 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
2d840 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
2d850 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
2d860 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
2d870 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
2d880 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2d890 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
2d8a0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 wise.)^.**.** ^S
2d8b0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
2d8c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
2d8d0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
2d8e0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
2d8f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
2d900 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
2d910 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
2d920 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
2d930 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
2d940 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
2d950 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
2d960 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
2d970 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
2d980 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 Mode].*/.int sq
2d990 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
2d9a0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a red_cache(int);.
2d9b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d9c0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 Attempt To Free
2d9d0 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a Heap Memory.**.
2d9e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2d9f0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
2da00 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
2da10 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 pts to free N by
2da20 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d tes.** of heap m
2da30 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 emory by dealloc
2da40 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 ating non-essent
2da50 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ial memory alloc
2da60 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 ations.** held b
2da70 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c y the database l
2da80 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 ibrary. Memory
2da90 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 used to cache d
2daa0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 atabase.** pages
2dab0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 to improve perf
2dac0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 ormance is an ex
2dad0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 ample of non-ess
2dae0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a ential memory..*
2daf0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * ^sqlite3_relea
2db00 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 se_memory() retu
2db10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2db20 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 f bytes actually
2db30 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 freed,.** which
2db40 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
2db50 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 r less than the
2db60 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
2db70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2db80 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
2db90 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2dba0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 I3REF: Impose A
2dbb0 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 Limit On Heap Si
2dbc0 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ze.**.** ^The sq
2dbd0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
2dbe0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 limit() interfac
2dbf0 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 e places a "soft
2dc00 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 " limit.** on th
2dc10 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
2dc20 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
2dc30 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 be allocated by
2dc40 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 SQLite..** ^If
2dc50 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f an internal allo
2dc60 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 cation is reques
2dc70 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 ted that would e
2dc80 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 xceed the.** sof
2dc90 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 t heap limit, [s
2dca0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2dcb0 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f emory()] is invo
2dcc0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f ked one or.** mo
2dcd0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 re times to free
2dce0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 up some space b
2dcf0 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 efore the alloca
2dd00 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 tion is performe
2dd10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 d..**.** ^The li
2dd20 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 mit is called "s
2dd30 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20 oft" because if
2dd40 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
2dd50 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 _memory()].** ca
2dd60 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 nnot free suffic
2dd70 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 ient memory to p
2dd80 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 revent the limit
2dd90 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 from being exce
2dda0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d eded,.** the mem
2ddb0 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 ory is allocated
2ddc0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 anyway and the
2ddd0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
2dde0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a n proceeds..**.*
2ddf0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 * ^A negative or
2de00 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 zero value for
2de10 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 N means that the
2de20 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 re is no soft he
2de30 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 ap limit and.**
2de40 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
2de50 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 _memory()] will
2de60 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
2de70 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 hen memory is ex
2de80 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 hausted..** ^The
2de90 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 default value f
2dea0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
2deb0 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a limit is zero..
2dec0 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d **.** ^(SQLite m
2ded0 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f akes a best effo
2dee0 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 rt to honor the
2def0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e soft heap limit.
2df00 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 .** But if the s
2df10 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 oft heap limit c
2df20 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 annot be honored
2df30 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c , execution will
2df40 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 .** continue wit
2df50 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f hout error or no
2df60 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 tification.)^ T
2df70 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c his is why the l
2df80 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 imit is.** calle
2df90 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 d a "soft" limit
2dfa0 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 . It is advisor
2dfb0 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 y only..**.** Pr
2dfc0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
2dfd0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 rsion 3.5.0, thi
2dfe0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 s routine only c
2dff0 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d onstrained the m
2e000 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
2e010 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ed by a single t
2e020 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 hread - the same
2e030 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
2e040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a this routine.**
2e050 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e runs. Beginnin
2e060 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 g with SQLite ve
2e070 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 rsion 3.5.0, the
2e080 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2e090 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 is.** applied t
2e0a0 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 o all threads. T
2e0b0 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 he value specifi
2e0c0 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 ed for the soft
2e0d0 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 heap limit.** is
2e0e0 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 an upper bound
2e0f0 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d on the total mem
2e100 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
2e110 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 or all threads.
2e120 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e In.** version 3.
2e130 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 5.0 there is no
2e140 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 mechanism for li
2e150 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 miting the heap
2e160 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 usage for.** ind
2e170 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e ividual threads.
2e180 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
2e190 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
2e1a0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
2e1b0 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 PI3REF: Extract
2e1c0 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 Metadata About A
2e1d0 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 Column Of A Tab
2e1e0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 le.**.** ^This r
2e1f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d outine returns m
2e200 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 etadata about a
2e210 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 specific column
2e220 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a of a specific.**
2e230 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
2e240 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 accessible using
2e250 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2e260 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
2e270 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 e.** passed as t
2e280 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f he first functio
2e290 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a n argument..**.*
2e2a0 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 * ^The column is
2e2b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
2e2c0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 he second, third
2e2d0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
2e2e0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 meters to.** thi
2e2f0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 s function. ^The
2e300 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2e310 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 r is either the
2e320 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
2e330 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d base.** (i.e. "m
2e340 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 ain", "temp", or
2e350 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 an attached dat
2e360 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e abase) containin
2e370 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a g the specified.
2e380 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c ** table or NULL
2e390 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c . ^If it is NULL
2e3a0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
2e3b0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
2e3c0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
2e3d0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
2e3e0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
2e3f0 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 ithm used by the
2e400 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2e410 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 to.** resolve u
2e420 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 nqualified table
2e430 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a references..**.
2e440 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e ** ^The third an
2e450 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
2e460 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
2e470 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 tion are the tab
2e480 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a le and column.**
2e490 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 name of the des
2e4a0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 ired column, res
2e4b0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 pectively. Neith
2e4c0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 er of these para
2e4d0 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 meters.** may be
2e4e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 NULL..**.** ^Me
2e4f0 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e tadata is return
2e500 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f ed by writing to
2e510 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 the memory loca
2e520 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 tions passed as
2e530 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 the 5th.** and s
2e540 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
2e550 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e ters to this fun
2e560 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 ction. ^Any of t
2e570 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d hese arguments m
2e580 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 ay be.** NULL, i
2e590 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
2e5a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 corresponding e
2e5b0 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 lement of metada
2e5c0 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a ta is omitted..*
2e5d0 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f *.** ^(<blockquo
2e5e0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
2e5f0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
2e600 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 ><th> Parameter
2e610 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 <th> Output<br>T
2e620 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 ype <th> Descri
2e630 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e ption.**.** <tr>
2e640 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f <td> 5th <td> co
2e650 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 nst char* <td> D
2e660 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e ata type.** <tr>
2e670 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f <td> 6th <td> co
2e680 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e nst char* <td> N
2e690 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 ame of default c
2e6a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2e6b0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 e.** <tr><td> 7t
2e6c0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 h <td> int
2e6d0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 <td> True if
2e6e0 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 column has a NOT
2e6f0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 NULL constraint
2e700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 .** <tr><td> 8th
2e710 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 <td> int
2e720 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 <td> True if c
2e730 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 olumn is part of
2e740 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 the PRIMARY KEY
2e750 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 .** <tr><td> 9th
2e760 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 <td> int
2e770 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 <td> True if c
2e780 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e olumn is [AUTOIN
2e790 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 CREMENT].** </ta
2e7a0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
2e7b0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 uote>)^.**.** ^T
2e7c0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
2e7d0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 d to by the char
2e7e0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 acter pointers r
2e7f0 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a eturned for the.
2e800 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 ** declaration t
2e810 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f ype and collatio
2e820 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 n sequence is va
2e830 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 lid only until t
2e840 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 he next.** call
2e850 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 to any SQLite AP
2e860 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a I function..**.*
2e870 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 * ^If the specif
2e880 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 ied table is act
2e890 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e ually a view, an
2e8a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
2e8b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2e8c0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
2e8d0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f ed column is "ro
2e8e0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 wid", "oid" or "
2e8f0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a _rowid_" and an.
2e900 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d ** [INTEGER PRIM
2e910 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 ARY KEY] column
2e920 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 has been explici
2e930 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 tly declared, th
2e940 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a en the output.**
2e950 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2e960 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c set for the expl
2e970 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
2e980 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 column. ^(If the
2e990 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c re is no.** expl
2e9a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
2e9b0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
2e9c0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 KEY] column, th
2e9d0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a en the output.**
2e9e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2e9f0 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a set as follows:.
2ea00 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 **.** <pre>.**
2ea10 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 data type: "I
2ea20 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 NTEGER".** c
2ea30 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2ea40 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 e: "BINARY".**
2ea50 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a not null: 0.*
2ea60 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 * primary ke
2ea70 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f y: 1.** auto
2ea80 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a increment: 0.**
2ea90 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 </pre>)^.**.**
2eaa0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^(This function
2eab0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 may load one or
2eac0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f more schemas fro
2ead0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 m database files
2eae0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 . If an.** error
2eaf0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
2eb00 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 his process, or
2eb10 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 if the requested
2eb20 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
2eb30 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f .** cannot be fo
2eb40 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 und, an [error c
2eb50 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2eb60 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 and an error me
2eb70 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e ssage left.** in
2eb80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2eb90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 onnection] (to b
2eba0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e e retrieved usin
2ebb0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 g sqlite3_errmsg
2ebc0 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ()).)^.**.** ^Th
2ebd0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 is API is only a
2ebe0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
2ebf0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
2ec00 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
2ec10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
2ec20 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d COLUMN_METADATA]
2ec30 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C-preprocessor
2ec40 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
2ec50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
2ec60 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 able_column_meta
2ec70 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 data(. sqlite3
2ec80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2ec90 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f /* Connectio
2eca0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f n handle */. co
2ecb0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
2ecc0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 e, /* Dat
2ecd0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 abase name or NU
2ece0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 LL */. const ch
2ecf0 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 ar *zTableName,
2ed00 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d /* Table nam
2ed10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2ed20 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 r *zColumnName,
2ed30 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d /* Column nam
2ed40 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
2ed50 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 t **pzDataType,
2ed60 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 /* OUTPUT: De
2ed70 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 clared data type
2ed80 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 */. char const
2ed90 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 **pzCollSeq,
2eda0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c /* OUTPUT: Col
2edb0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
2edc0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 name */. int *p
2edd0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 NotNull,
2ede0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
2edf0 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c True if NOT NUL
2ee00 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 L constraint exi
2ee10 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 sts */. int *pP
2ee20 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 rimaryKey,
2ee30 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
2ee40 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 True if column p
2ee50 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 art of PK */. i
2ee60 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 nt *pAutoinc
2ee70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
2ee80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f TPUT: True if co
2ee90 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 lumn is auto-inc
2eea0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a rement */.);../*
2eeb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
2eec0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a ad An Extension.
2eed0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
2eee0 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 rface loads an S
2eef0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
2ef00 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 library from the
2ef10 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a named file..**.
2ef20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2ef30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2ef40 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
2ef50 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a pts to load an.*
2ef60 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 * SQLite extensi
2ef70 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 on library conta
2ef80 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 ined in the file
2ef90 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 zFile..**.** ^T
2efa0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 he entry point i
2efb0 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 s zProc..** ^zPr
2efc0 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 oc may be 0, in
2efd0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
2efe0 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 ame of the entry
2eff0 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c point.** defaul
2f000 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 ts to "sqlite3_e
2f010 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a xtension_init"..
2f020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2f030 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2f040 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2f050 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b ns.** [SQLITE_OK
2f060 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
2f070 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2f080 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 if something goe
2f090 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 s wrong..** ^If
2f0a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
2f0b0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 and pzErrMsg is
2f0c0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a not 0, then the.
2f0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 ** [sqlite3_load
2f0e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e _extension()] in
2f0f0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 terface shall at
2f100 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c tempt to.** fill
2f110 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 *pzErrMsg with
2f120 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
2f130 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d xt stored in mem
2f140 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 ory.** obtained
2f150 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2f160 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c lloc()]. The cal
2f170 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ling function.**
2f180 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 should free thi
2f190 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c s memory by call
2f1a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
2f1b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 e()]..**.** ^Ext
2f1c0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d ension loading m
2f1d0 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 ust be enabled u
2f1e0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
2f1f0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
2f200 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 ension()] prior
2f210 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 to calling this
2f220 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 API,.** otherwis
2f230 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 e an error will
2f240 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a be returned..**.
2f250 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
2f260 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 [load_extension(
2f270 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
2f280 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2f290 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
2f2a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2f2b0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
2f2c0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
2f2d0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
2f2e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
2f2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
2f300 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
2f310 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
2f320 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
2f330 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
2f340 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
2f350 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
2f360 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
2f370 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
2f380 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
2f390 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
2f3a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
2f3b0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
2f3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f3d0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
2f3e0 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c able Extension L
2f3f0 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f oading.**.** ^So
2f400 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 as not to open
2f410 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 security holes i
2f420 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 n older applicat
2f430 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a ions that are.**
2f440 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 unprepared to d
2f450 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 eal with extensi
2f460 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 on loading, and
2f470 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 as a means of di
2f480 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e sabling.** exten
2f490 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 sion loading whi
2f4a0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 le evaluating us
2f4b0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 er-entered SQL,
2f4c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 the following AP
2f4d0 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 I.** is provided
2f4e0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 to turn the [sq
2f4f0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
2f500 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 sion()] mechanis
2f510 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a m on and off..**
2f520 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c .** ^Extension l
2f530 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 oading is off by
2f540 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 default. See ti
2f550 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e cket #1863..** ^
2f560 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 Call the sqlite3
2f570 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
2f580 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 ension() routine
2f590 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a with onoff==1.*
2f5a0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 * to turn extens
2f5b0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 ion loading on a
2f5c0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 nd call it with
2f5d0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e onoff==0 to turn
2f5e0 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 .** it back off
2f5f0 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 again..*/.int sq
2f600 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 lite3_enable_loa
2f610 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 d_extension(sqli
2f620 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f te3 *db, int ono
2f630 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
2f640 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 3REF: Automatica
2f650 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 lly Load An Exte
2f660 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 nsions.**.** ^Th
2f670 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e is API can be in
2f680 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d voked at program
2f690 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 startup in orde
2f6a0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a r to register.**
2f6b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 one or more sta
2f6c0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 tically linked e
2f6d0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 xtensions that w
2f6e0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 ill be available
2f6f0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b .** to all new [
2f700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2f710 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ions]..**.** ^(T
2f720 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
2f730 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 es a pointer to
2f740 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e the extension en
2f750 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 try point.** in
2f760 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 an array that is
2f770 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2f780 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2f790 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a ]. That memory.
2f7a0 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 ** is deallocate
2f7b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 d by [sqlite3_re
2f7c0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
2f7d0 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e on()].)^.**.** ^
2f7e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
2f7f0 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e gisters an exten
2f800 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 sion entry point
2f810 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f that is.** auto
2f820 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 matically invoke
2f830 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 d whenever a new
2f840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2f850 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 ction].** is ope
2f860 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ned using [sqlit
2f870 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2f880 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a ite3_open16()],.
2f890 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
2f8a0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 pen_v2()]..** ^D
2f8b0 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 uplicate extensi
2f8c0 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 ons are detected
2f8d0 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 so calling this
2f8e0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 routine.** mult
2f8f0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 iple times with
2f900 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 the same extensi
2f910 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a on is harmless..
2f920 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 ** ^Automatic ex
2f930 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 tensions apply a
2f940 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 cross all thread
2f950 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
2f960 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
2f970 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f (void (*xEntryPo
2f980 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a int)(void));../*
2f990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2f9a0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 set Automatic Ex
2f9b0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a tension Loading.
2f9c0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e **.** ^(This fun
2f9d0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
2f9e0 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ll previously re
2f9f0 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 gistered automat
2fa00 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 ic.** extensions
2fa10 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 . It undoes the
2fa20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 effect of all pr
2fa30 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ior.** [sqlite3_
2fa40 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 auto_extension()
2fa50 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a ] calls.)^.**.**
2fa60 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
2fa70 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 disables automat
2fa80 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e ic extensions in
2fa90 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f all threads..*/
2faa0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2fab0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
2fac0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a on(void);../*.**
2fad0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 The interface t
2fae0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 o the virtual-ta
2faf0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 ble mechanism is
2fb00 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
2fb10 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
2fb20 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
2fb30 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
2fb40 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
2fb50 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
2fb60 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
2fb70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
2fb80 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
2fb90 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
2fba0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
2fbb0 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
2fbc0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
2fbd0 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
2fbe0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
2fbf0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
2fc00 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
2fc10 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
2fc20 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
2fc30 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 nt..*/../*.** St
2fc40 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 ructures used by
2fc50 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
2fc60 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a le interface.*/.
2fc70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2fc80 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 qlite3_vtab sqli
2fc90 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 te3_vtab;.typede
2fca0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2fcb0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 _index_info sqli
2fcc0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a te3_index_info;.
2fcd0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2fce0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
2fcf0 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f or sqlite3_vtab_
2fd00 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 cursor;.typedef
2fd10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
2fd20 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f odule sqlite3_mo
2fd30 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 dule;../*.** CAP
2fd40 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
2fd50 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b able Object.** K
2fd60 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
2fd70 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c _module {virtual
2fd80 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a table module}.*
2fd90 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 *.** This struct
2fda0 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 ure, sometimes c
2fdb0 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 alled a a "virtu
2fdc0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 al table module"
2fdd0 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 , .** defines th
2fde0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2fdf0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 of a [virtual t
2fe00 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 ables]. .** Thi
2fe10 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 s structure cons
2fe20 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d ists mostly of m
2fe30 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d ethods for the m
2fe40 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 odule..**.** ^A
2fe50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
2fe60 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 dule is created
2fe70 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 by filling in a
2fe80 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e persistent.** in
2fe90 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 stance of this s
2fea0 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 tructure and pas
2feb0 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 sing a pointer t
2fec0 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a o that instance.
2fed0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
2fee0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 reate_module()]
2fef0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 or [sqlite3_crea
2ff00 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e te_module_v2()].
2ff10 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 .** ^The registr
2ff20 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 ation remains va
2ff30 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 lid until it is
2ff40 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 replaced by a di
2ff50 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c fferent.** modul
2ff60 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b e or until the [
2ff70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ff80 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 ion] closes. Th
2ff90 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 e content.** of
2ffa0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d this structure m
2ffb0 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 ust not change w
2ffc0 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 hile it is regis
2ffd0 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e tered with.** an
2ffe0 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
2fff0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 ction..*/.struct
30000 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
30010 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
30020 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 ;. int (*xCreat
30030 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 e)(sqlite3*, voi
30040 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 d *pAux,.
30050 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
30060 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f , const char *co
30070 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 nst*argv,.
30080 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
30090 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 _vtab **ppVTab,
300a0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 char**);. int (
300b0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 *xConnect)(sqlit
300c0 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c e3*, void *pAux,
300d0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
300e0 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 int argc, const
300f0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 char *const*argv
30100 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
30110 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a sqlite3_vtab **
30120 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b ppVTab, char**);
30130 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e . int (*xBestIn
30140 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 dex)(sqlite3_vta
30150 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 b *pVTab, sqlite
30160 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 3_index_info*);.
30170 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e int (*xDisconn
30180 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ect)(sqlite3_vta
30190 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
301a0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c (*xDestroy)(sql
301b0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
301c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e );. int (*xOpen
301d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
301e0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 pVTab, sqlite3_v
301f0 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 tab_cursor **ppC
30200 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a ursor);. int (*
30210 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
30220 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
30230 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 int (*xFilter)(
30240 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
30250 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d sor*, int idxNum
30260 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 , const char *id
30270 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 xStr,.
30280 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 int argc,
30290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a sqlite3_value **
302a0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 argv);. int (*x
302b0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 Next)(sqlite3_vt
302c0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
302d0 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 nt (*xEof)(sqlit
302e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
302f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d ;. int (*xColum
30300 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f n)(sqlite3_vtab_
30310 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 cursor*, sqlite3
30320 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
30330 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 . int (*xRowid)
30340 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
30350 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 rsor*, sqlite3_i
30360 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 nt64 *pRowid);.
30370 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 int (*xUpdate)(
30380 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 sqlite3_vtab *,
30390 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c int, sqlite3_val
303a0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 ue **, sqlite3_i
303b0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 nt64 *);. int (
303c0 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 *xBegin)(sqlite3
303d0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
303e0 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
303f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
30400 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d b);. int (*xCom
30410 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 mit)(sqlite3_vta
30420 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
30430 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 (*xRollback)(sq
30440 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
30450 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e b);. int (*xFin
30460 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 dFunction)(sqlit
30470 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 e3_vtab *pVtab,
30480 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 int nArg, const
30490 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 char *zName,.
304a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
304b0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 void (**pxFu
304c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
304d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
304e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 _value**),.
304f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30500 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b void **ppArg);
30510 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 . int (*xRename
30520 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
30530 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 pVtab, const cha
30540 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a r *zNew);.};../*
30550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
30560 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 rtual Table Inde
30570 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e xing Information
30580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
30590 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
305a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
305b0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 e3_index_info st
305c0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 ructure and its
305d0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 substructures is
305e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 used to.** pass
305f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 information int
30600 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 o and receive th
30610 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 e reply from the
30620 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a [xBestIndex].**
30630 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 method of a [vi
30640 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
30650 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 le]. The fields
30660 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a under **Inputs*
30670 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 * are the.** inp
30680 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 uts to xBestInde
30690 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f x and are read-o
306a0 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 nly. xBestIndex
306b0 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 inserts its.**
306c0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 results into the
306d0 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 **Outputs** fie
306e0 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 lds..**.** ^(The
306f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 aConstraint[] a
30700 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 rray records WHE
30710 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 RE clause constr
30720 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 aints of the for
30730 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f m:.**.** <pre>co
30740 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 lumn OP expr</pr
30750 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f e>.**.** where O
30760 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c P is =, <, &l
30770 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 t;=, >, or &g
30780 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 t;=.)^ ^(The pa
30790 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f rticular operato
307a0 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 r is.** stored i
307b0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e n aConstraint[].
307c0 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 op.)^ ^(The ind
307d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
307e0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a is stored in.**
307f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 aConstraint[].i
30800 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f Column.)^ ^(aCo
30810 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c nstraint[].usabl
30820 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 e is TRUE if the
30830 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 .** expr on the
30840 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 right-hand side
30850 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 can be evaluated
30860 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 (and thus the c
30870 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 onstraint.** is
30880 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 usable) and fals
30890 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 e if it cannot.)
308a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 ^.**.** ^The opt
308b0 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 imizer automatic
308c0 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 ally inverts ter
308d0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 ms of the form "
308e0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a expr OP column".
308f0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 ** and makes oth
30900 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f er simplificatio
30910 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 ns to the WHERE
30920 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 clause in an att
30930 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 empt to.** get a
30940 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 s many WHERE cla
30950 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 use terms into t
30960 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 he form shown ab
30970 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e ove as possible.
30980 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 .** ^The aConstr
30990 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c aint[] array onl
309a0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 y reports WHERE
309b0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 clause terms tha
309c0 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e t are.** relevan
309d0 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 t to the particu
309e0 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c lar virtual tabl
309f0 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e e being queried.
30a00 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 .**.** ^Informat
30a10 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 ion about the OR
30a20 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 DER BY clause is
30a30 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 stored in aOrde
30a40 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 rBy[]..** ^Each
30a50 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 term of aOrderBy
30a60 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d records a colum
30a70 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 n of the ORDER B
30a80 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 Y clause..**.**
30a90 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d The [xBestIndex]
30aa0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c method must fil
30ab0 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 l aConstraintUsa
30ac0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d ge[] with inform
30ad0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 ation.** about w
30ae0 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 hat parameters t
30af0 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 o pass to xFilte
30b00 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 r. ^If argvInde
30b10 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 x>0 then.** the
30b20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 right-hand side
30b30 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e of the correspon
30b40 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 ding aConstraint
30b50 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a [] is evaluated.
30b60 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 ** and becomes t
30b70 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 he argvIndex-th
30b80 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 entry in argv.
30b90 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 ^(If aConstraint
30ba0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
30bb0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
30bc0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
30bd0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
30be0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
30bf0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
30c00 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
30c10 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
30c20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 SQLite.)^.**.**
30c30 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 ^The idxNum and
30c40 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 idxPtr values ar
30c50 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 e recorded and p
30c60 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a assed into the.*
30c70 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 * [xFilter] meth
30c80 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 od..** ^[sqlite3
30c90 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 _free()] is used
30ca0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 to free idxPtr
30cb0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a if and only if.*
30cc0 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 * needToFreeIdxP
30cd0 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a tr is true..**.*
30ce0 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f * ^The orderByCo
30cf0 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 nsumed means tha
30d00 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 t output from [x
30d10 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 Filter]/[xNext]
30d20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a will occur in.**
30d30 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 the correct ord
30d40 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 er to satisfy th
30d50 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
30d60 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 e so that no sep
30d70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 arate.** sorting
30d80 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 step is require
30d90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 d..**.** ^The es
30da0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 timatedCost valu
30db0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 e is an estimate
30dc0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 of the cost of
30dd0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 doing the.** par
30de0 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 ticular lookup.
30df0 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 A full scan of
30e00 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 a table with N e
30e10 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
30e20 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 ve.** a cost of
30e30 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 N. A binary sea
30e40 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f rch of a table o
30e50 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 f N entries shou
30e60 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 ld have a.** cos
30e70 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 t of approximate
30e80 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 ly log(N)..*/.st
30e90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
30ea0 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 ex_info {. /* I
30eb0 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e nputs */. int n
30ec0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 Constraint;
30ed0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
30ee0 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 of entries in aC
30ef0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 onstraint */. s
30f00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
30f10 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b dex_constraint {
30f20 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d . int iColum
30f30 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 n;
30f40 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 /* Column on lef
30f50 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 t-hand side of c
30f60 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 onstraint */.
30f70 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
30f80 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 op; /* C
30f90 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 onstraint operat
30fa0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 or */. unsig
30fb0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b ned char usable;
30fc0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 /* True if
30fd0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 this constraint
30fe0 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 is usable */.
30ff0 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 int iTermOffse
31000 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 t; /* U
31010 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d sed internally -
31020 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 xBestIndex shou
31030 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d ld ignore */. }
31040 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 *aConstraint;
31050 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 /* Tab
31060 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 le of WHERE clau
31070 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a se constraints *
31080 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 /. int nOrderBy
31090 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f ; /
310a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d * Number of term
310b0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 s in the ORDER B
310c0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 Y clause */. st
310d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
310e0 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 ex_orderby {.
310f0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
31100 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
31110 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a olumn number */.
31120 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
31130 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f ar desc; /
31140 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e * True for DESC.
31150 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e False for ASC.
31160 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 */. } *aOrderB
31170 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 y;
31180 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 /* The ORDER BY
31190 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 clause */. /*
311a0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 Outputs */. str
311b0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
311c0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 x_constraint_usa
311d0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 ge {. int arg
311e0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 vIndex;
311f0 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 /* if >0, cons
31200 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f traint is part o
31210 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 f argv to xFilte
31220 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 r */. unsigne
31230 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 d char omit;
31240 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 /* Do not code
31250 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 a test for this
31260 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 constraint */.
31270 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 } *aConstraintU
31280 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e sage;. int idxN
31290 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 um;
312a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 /* Number use
312b0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 d to identify th
312c0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 e index */. cha
312d0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 r *idxStr;
312e0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e /* Strin
312f0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 g, possibly obta
31300 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
31310 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 3_malloc */. in
31320 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 t needToFreeIdxS
31330 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 tr; /* Free
31340 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 idxStr using sq
31350 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 lite3_free() if
31360 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 true */. int or
31370 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 derByConsumed;
31380 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 /* True if
31390 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 output is alread
313a0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 y ordered */. d
313b0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 ouble estimatedC
313c0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 ost; /* Est
313d0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 imated cost of u
313e0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 sing this index
313f0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 */.};.#define SQ
31400 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
31410 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 RAINT_EQ 2.#d
31420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
31430 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 EX_CONSTRAINT_GT
31440 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
31450 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
31460 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 RAINT_LE 8.#d
31470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
31480 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 EX_CONSTRAINT_LT
31490 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
314a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
314b0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a TRAINT_GE 32.
314c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
314d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
314e0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 MATCH 64../*.**
314f0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
31500 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 er A Virtual Tab
31510 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le Implementatio
31520 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 n.**.** ^These r
31530 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
31540 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e to register a n
31550 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ew [virtual tabl
31560 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a e module] name..
31570 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 ** ^Module names
31580 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 must be registe
31590 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 red before.** cr
315a0 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 eating a new [vi
315b0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 rtual table] usi
315c0 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e ng the module an
315d0 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 d before using a
315e0 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 .** preexisting
315f0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 [virtual table]
31600 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a for the module..
31610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c **.** ^The modul
31620 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 e name is regist
31630 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 ered on the [dat
31640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
31650 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 ] specified.** b
31660 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 y the first para
31670 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d meter. ^The nam
31680 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 e of the module
31690 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 is given by the
316a0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
316b0 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 eter. ^The thir
316c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
316d0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 pointer to.** t
316e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
316f0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 n of the [virtua
31700 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e l table module].
31710 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a ^The fourth.*
31720 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 * parameter is a
31730 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 n arbitrary clie
31740 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 nt data pointer
31750 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 that is passed t
31760 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 hrough.** into t
31770 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 he [xCreate] and
31780 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 [xConnect] meth
31790 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 ods of the virtu
317a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a al table module.
317b0 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 ** when a new vi
317c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 rtual table is b
317d0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 e being created
317e0 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 or reinitialized
317f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
31800 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
31810 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 le_v2() interfac
31820 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61 e has a fifth pa
31830 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
31840 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
31850 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f a destructor fo
31860 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 r the pClientDat
31870 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c a. ^SQLite will
31880 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 .** invoke the d
31890 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
318a0 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 on (if it is not
318b0 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 NULL) when SQLi
318c0 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 te.** no longer
318d0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e needs the pClien
318e0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 tData pointer.
318f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 ^The sqlite3_cre
31900 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 ate_module().**
31910 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75 interface is equ
31920 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 ivalent to sqlit
31930 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
31940 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c _v2() with a NUL
31950 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e L.** destructor.
31960 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
31970 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 create_module(.
31980 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
31990 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
319a0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e QLite connection
319b0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 to register mod
319c0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f ule with */. co
319d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
319e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 /* Name
319f0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a of the module *
31a00 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 /. const sqlite
31a10 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 3_module *p, /
31a20 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 * Methods for th
31a30 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f e module */. vo
31a40 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 id *pClientData
31a50 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 /* Clie
31a60 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 nt data for xCre
31a70 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a ate/xConnect */.
31a80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
31a90 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 reate_module_v2(
31aa0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
31ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
31ac0 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 SQLite connecti
31ad0 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d on to register m
31ae0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 odule with */.
31af0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
31b00 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 e, /* Na
31b10 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 me of the module
31b20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 */. const sqli
31b30 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 te3_module *p,
31b40 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
31b50 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 the module */.
31b60 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 void *pClientDat
31b70 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c a, /* Cl
31b80 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 ient data for xC
31b90 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a reate/xConnect *
31ba0 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 /. void(*xDestr
31bb0 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f oy)(void*) /
31bc0 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 * Module destruc
31bd0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a tor function */.
31be0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
31bf0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
31c00 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 e Instance Objec
31c10 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 t.** KEYWORDS: s
31c20 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a qlite3_vtab.**.*
31c30 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c * Every [virtual
31c40 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 table module] i
31c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 mplementation us
31c60 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a es a subclass.**
31c70 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
31c80 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 to describe a pa
31c90 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 rticular instanc
31ca0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 e.** of the [vir
31cb0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 tual table]. Ea
31cc0 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c ch subclass will
31cd0 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 .** be tailored
31ce0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
31cf0 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 needs of the mod
31d00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
31d10 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f on..** The purpo
31d20 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 se of this super
31d30 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 class is to defi
31d40 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 ne certain field
31d50 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f s that are.** co
31d60 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 mmon to all modu
31d70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
31d80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 ns..**.** ^Virtu
31d90 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 al tables method
31da0 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 s can set an err
31db0 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 or message by as
31dc0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 signing a.** str
31dd0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ing obtained fro
31de0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e m [sqlite3_mprin
31df0 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 tf()] to zErrMsg
31e00 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 . The method sh
31e10 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 ould.** take car
31e20 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 e that any prior
31e30 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 string is freed
31e40 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 by a call to [s
31e50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a qlite3_free()].*
31e60 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 * prior to assig
31e70 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e ning a new strin
31e80 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e g to zErrMsg. ^
31e90 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 After the error
31ea0 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 message.** is de
31eb0 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 livered up to th
31ec0 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 e client applica
31ed0 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 tion, the string
31ee0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
31ef0 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 ically.** freed
31f00 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 by sqlite3_free(
31f10 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 ) and the zErrMs
31f20 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 g field will be
31f30 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 zeroed..*/.struc
31f40 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b t sqlite3_vtab {
31f50 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
31f60 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 _module *pModule
31f70 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 ; /* The module
31f80 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 for this virtua
31f90 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 l table */. int
31fa0 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 nRef;
31fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
31fc0 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a NO LONGER USED *
31fd0 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 /. char *zErrMs
31fe0 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g;
31ff0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 /* Error mes
32000 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 sage from sqlite
32010 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 3_mprintf() */.
32020 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
32030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32040 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 s will typically
32050 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 add additional
32060 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a fields */.};../*
32070 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
32080 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 rtual Table Curs
32090 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 or Object.** KEY
320a0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
320b0 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 tab_cursor {virt
320c0 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 ual table cursor
320d0 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 }.**.** Every [v
320e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
320f0 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ule] implementat
32100 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c ion uses a subcl
32110 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ass of the.** fo
32120 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
32130 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 e to describe cu
32140 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 rsors that point
32150 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 into the.** [vi
32160 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 rtual table] and
32170 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 are used.** to
32180 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 loop through the
32190 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 virtual table.
321a0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 Cursors are cre
321b0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ated using the.*
321c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c * [sqlite3_modul
321d0 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d e.xOpen | xOpen]
321e0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d method of the m
321f0 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 odule and are de
32200 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 stroyed.** by th
32210 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c e [sqlite3_modul
32220 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 e.xClose | xClos
32230 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 e] method. Curs
32240 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 ors are used.**
32250 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d by the [xFilter]
32260 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 , [xNext], [xEof
32270 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e ], [xColumn], an
32280 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f d [xRowid] metho
32290 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 ds.** of the mod
322a0 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c ule. Each modul
322b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
322c0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 will define.**
322d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 the content of a
322e0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 cursor structur
322f0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 e to suit its ow
32300 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 n needs..**.** T
32310 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 his superclass e
32320 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 xists in order t
32330 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 o define fields
32340 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 of the cursor th
32350 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e at.** are common
32360 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e to all implemen
32370 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 tations..*/.stru
32380 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f ct sqlite3_vtab_
32390 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 cursor {. sqlit
323a0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 e3_vtab *pVtab;
323b0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 /* Virtual
323c0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 table of this cu
323d0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 rsor */. /* Vir
323e0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
323f0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
32400 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
32410 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
32420 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
32430 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 I3REF: Declare T
32440 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 he Schema Of A V
32450 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a irtual Table.**.
32460 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 ** ^The [xCreate
32470 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d ] and [xConnect]
32480 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a methods of a.**
32490 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
324a0 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 module] call thi
324b0 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 s interface.** t
324c0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f o declare the fo
324d0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 rmat (the names
324e0 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 and datatypes of
324f0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 the columns) of
32500 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 .** the virtual
32510 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c tables they impl
32520 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ement..*/.int sq
32530 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 lite3_declare_vt
32540 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e ab(sqlite3*, con
32550 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a st char *zSQL);.
32560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32570 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 Overload A Func
32580 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 tion For A Virtu
32590 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e al Table.**.** ^
325a0 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 (Virtual tables
325b0 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 can provide alte
325c0 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e rnative implemen
325d0 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 tations of funct
325e0 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 ions.** using th
325f0 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e e [xFindFunction
32600 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 ] method of the
32610 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
32620 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 odule]. .** But
32630 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 global versions
32640 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 of those functi
32650 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 ons.** must exis
32660 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 t in order to be
32670 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a overloaded.)^.*
32680 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 *.** ^(This API
32690 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f makes sure a glo
326a0 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 bal version of a
326b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
326c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e particular.** n
326d0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f ame and number o
326e0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 f parameters exi
326f0 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 sts. If no such
32700 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 function exists
32710 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 .** before this
32720 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 API is called, a
32730 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
32740 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 created.)^ ^Th
32750 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32760 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 .** of the new f
32770 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 unction always c
32780 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 auses an excepti
32790 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e on to be thrown.
327a0 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 So.** the new
327b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 function is not
327c0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e good for anythin
327d0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 g by itself. It
327e0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 s only.** purpos
327f0 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 e is to be a pla
32800 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f ceholder functio
32810 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 n that can be ov
32820 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 erloaded.** by a
32830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
32840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
32850 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 _overload_functi
32860 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e on(sqlite3*, con
32870 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 st char *zFuncNa
32880 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a me, int nArg);..
32890 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 /*.** The interf
328a0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
328b0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
328c0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 sm defined above
328d0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 (back up.** to
328e0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b a comment remark
328f0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 ably similar to
32900 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 this one) is cur
32910 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
32920 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
32930 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
32940 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
32950 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
32960 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
32970 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
32980 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
32990 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
329a0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
329b0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
329c0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
329d0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
329e0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
329f0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
32a00 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
32a10 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
32a20 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
32a30 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
32a40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
32a50 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 EF: A Handle To
32a60 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 An Open BLOB.**
32a70 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 KEYWORDS: {BLOB
32a80 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 handle} {BLOB ha
32a90 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ndles}.**.** An
32aa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
32ab0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
32ac0 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 ts an open BLOB
32ad0 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c on which.** [sql
32ae0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
32af0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
32b00 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 B I/O] can be pe
32b10 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a rformed..** ^Obj
32b20 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 ects of this typ
32b30 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 e are created by
32b40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
32b50 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 pen()].** and de
32b60 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
32b70 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
32b80 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 ]..** ^The [sqli
32b90 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
32ba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
32bb0 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 ob_write()] inte
32bc0 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 rfaces.** can be
32bd0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 used to read or
32be0 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 write small sub
32bf0 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 sections of the
32c00 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 BLOB..** ^The [s
32c10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 qlite3_blob_byte
32c20 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 s()] interface r
32c30 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 eturns the size
32c40 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 of the BLOB in b
32c50 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ytes..*/.typedef
32c60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
32c70 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f blob sqlite3_blo
32c80 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 b;../*.** CAPI3R
32c90 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 EF: Open A BLOB
32ca0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 For Incremental
32cb0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 I/O.**.** ^(This
32cc0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e interfaces open
32cd0 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s a [BLOB handle
32ce0 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 | handle] to th
32cf0 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a e BLOB located.*
32d00 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 * in row iRow, c
32d10 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 olumn zColumn, t
32d20 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 able zTable in d
32d30 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 atabase zDb;.**
32d40 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
32d50 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 the same BLOB th
32d60 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 at would be sele
32d70 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c cted by:.**.** <
32d80 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 pre>.** SELE
32d90 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 CT zColumn FROM
32da0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 zDb.zTable WHERE
32db0 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b [rowid] = iRow;
32dc0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a .** </pre>)^.**.
32dd0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 ** ^If the flags
32de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f parameter is no
32df0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 n-zero, then the
32e00 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 BLOB is opened
32e10 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 for read.** and
32e20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 write access. ^I
32e30 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 f it is zero, th
32e40 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 e BLOB is opened
32e50 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 for read access
32e60 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 ..** ^It is not
32e70 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e possible to open
32e80 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 a column that i
32e90 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 s part of an ind
32ea0 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a ex or primary .*
32eb0 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e * key for writin
32ec0 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 g. ^If [foreign
32ed0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d key constraints]
32ee0 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 are enabled, it
32ef0 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 is .** not poss
32f00 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 ible to open a c
32f10 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 olumn that is pa
32f20 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b rt of a [child k
32f30 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e ey] for writing.
32f40 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 .**.** ^Note tha
32f50 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e t the database n
32f60 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 ame is not the f
32f70 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e ilename that con
32f80 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 tains.** the dat
32f90 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 abase but rather
32fa0 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 the symbolic na
32fb0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
32fc0 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 se that.** appea
32fd0 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 rs after the AS
32fe0 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 keyword when the
32ff0 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e database is con
33000 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 nected using [AT
33010 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 TACH]..** ^For t
33020 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
33030 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 file, the datab
33040 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 ase name is "mai
33050 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 n"..** ^For TEMP
33060 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 tables, the dat
33070 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 abase name is "t
33080 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e emp"..**.** ^(On
33090 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
330a0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
330b0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 d and the new [B
330c0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 LOB handle] is w
330d0 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 ritten.** to *pp
330e0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 Blob. Otherwise
330f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
33100 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
33110 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a *ppBlob is set.*
33120 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 * to be a null p
33130 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 ointer.)^.** ^Th
33140 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 is function sets
33150 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
33160 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 onnection] error
33170 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 code and messag
33180 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 e.** accessible
33190 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 via [sqlite3_err
331a0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c code()] and [sql
331b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 ite3_errmsg()] a
331c0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 nd related.** fu
331d0 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 nctions. ^Note t
331e0 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 hat the *ppBlob
331f0 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 variable is alwa
33200 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 ys initialized i
33210 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 n a.** way that
33220 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f makes it safe to
33230 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
33240 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f _blob_close()] o
33250 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 n *ppBlob.** reg
33260 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 ardless of the s
33270 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
33280 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e e of this routin
33290 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 e..**.** ^(If th
332a0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f e row that a BLO
332b0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 B handle points
332c0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 to is modified b
332d0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d y an.** [UPDATE]
332e0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 , [DELETE], or b
332f0 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 y [ON CONFLICT]
33300 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 side-effects.**
33310 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 then the BLOB ha
33320 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 ndle is marked a
33330 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 s "expired"..**
33340 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 This is true if
33350 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 any column of th
33360 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 e row is changed
33370 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a , even a column.
33380 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 ** other than th
33390 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 e one the BLOB h
333a0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e andle is open on
333b0 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f .)^.** ^Calls to
333c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
333d0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ead()] and [sqli
333e0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
333f0 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 ] for.** a expir
33400 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 ed BLOB handle f
33410 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 ail with an retu
33420 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 rn code of [SQLI
33430 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 TE_ABORT]..** ^(
33440 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 Changes written
33450 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f into a BLOB prio
33460 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 r to the BLOB ex
33470 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a piring are not.*
33480 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 * rolled back by
33490 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 the expiration
334a0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 of the BLOB. Su
334b0 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ch changes will
334c0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f eventually.** co
334d0 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e mmit if the tran
334e0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 saction continue
334f0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e s to completion.
33500 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 )^.**.** ^Use th
33510 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
33520 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 bytes()] interfa
33530 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ce to determine
33540 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 the size of.** t
33550 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 he opened blob.
33560 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 ^The size of a
33570 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 blob may not be
33580 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a changed by this.
33590 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 ** interface. U
335a0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 se the [UPDATE]
335b0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 SQL command to c
335c0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f hange the size o
335d0 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a f a.** blob..**.
335e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
335f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
33600 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
33610 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
33620 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ] interfaces.**
33630 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e and the built-in
33640 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 [zeroblob] SQL
33650 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 function can be
33660 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 used, if desired
33670 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 ,.** to create a
33680 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 n empty, zero-fi
33690 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 lled blob in whi
336a0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ch to read or wr
336b0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 ite using.** thi
336c0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
336d0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 ** To avoid a re
336e0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 source leak, eve
336f0 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 ry open [BLOB ha
33700 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 ndle] should eve
33710 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 ntually.** be re
33720 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c leased by a call
33730 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
33740 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 b_close()]..*/.i
33750 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
33760 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a open(. sqlite3*
33770 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
33780 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 zDb,. const cha
33790 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e r *zTable,. con
337a0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e st char *zColumn
337b0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ,. sqlite3_int6
337c0 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 4 iRow,. int fl
337d0 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 ags,. sqlite3_b
337e0 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a lob **ppBlob.);.
337f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33800 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 Close A BLOB Ha
33810 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 ndle.**.** ^Clos
33820 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 es an open [BLOB
33830 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 handle]..**.**
33840 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 ^Closing a BLOB
33850 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 shall cause the
33860 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
33870 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a ion to commit.**
33880 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f if there are no
33890 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f other BLOBs, no
338a0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 pending prepare
338b0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e d statements, an
338c0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 d the.** databas
338d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
338e0 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d in [autocommit m
338f0 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 ode]..** ^If any
33900 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 writes were mad
33910 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 e to the BLOB, t
33920 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c hey might be hel
33930 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e d in cache.** un
33940 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 til the close op
33950 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 eration if they
33960 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 will fit..**.**
33970 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c ^(Closing the BL
33980 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 OB often forces
33990 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f the changes.** o
339a0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 ut to disk and s
339b0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 o if any I/O err
339c0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 ors occur, they
339d0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 will likely occu
339e0 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 r.** at the time
339f0 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 when the BLOB i
33a00 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 s closed. Any e
33a10 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 rrors that occur
33a20 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 during.** closi
33a30 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 ng are reported
33a40 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 as a non-zero re
33a50 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a turn value.)^.**
33a60 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 .** ^(The BLOB i
33a70 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 s closed uncondi
33a80 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 tionally. Even
33a90 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 if this routine
33aa0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 returns.** an er
33ab0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c ror code, the BL
33ac0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 OB is still clos
33ad0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c ed.)^.**.** ^Cal
33ae0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
33af0 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f e with a null po
33b00 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77 inter (such as w
33b10 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
33b20 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 .** by a failed
33b30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
33b40 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 _blob_open()]) i
33b50 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
33b60 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 op..*/.int sqlit
33b70 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 e3_blob_close(sq
33b80 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a lite3_blob *);..
33b90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33ba0 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 Return The Size
33bb0 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a Of An Open BLOB.
33bc0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 **.** ^Returns t
33bd0 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
33be0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 of the BLOB acc
33bf0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 essible via the
33c00 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
33c10 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 opened [BLOB ha
33c20 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c ndle] in its onl
33c30 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 y argument. ^Th
33c40 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c e.** incremental
33c50 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e blob I/O routin
33c60 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 es can only read
33c70 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 or overwriting
33c80 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 existing.** blob
33c90 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 content; they c
33ca0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 annot change the
33cb0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e size of a blob.
33cc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
33cd0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f ine only works o
33ce0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 n a [BLOB handle
33cf0 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e ] which has been
33d00 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 created.** by a
33d10 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
33d20 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
33d30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
33d40 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f and which has no
33d50 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 t.** been closed
33d60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
33d70 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 b_close()]. Pas
33d80 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 sing any other p
33d90 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 ointer in.** to
33da0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 this routine res
33db0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
33dc0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
33dd0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
33de0 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ior..*/.int sqli
33df0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 te3_blob_bytes(s
33e00 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a qlite3_blob *);.
33e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33e20 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 Read Data From
33e30 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 A BLOB Increment
33e40 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ally.**.** ^(Thi
33e50 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 s function is us
33e60 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 ed to read data
33e70 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c from an open [BL
33e80 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 OB handle] into
33e90 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 a.** caller-supp
33ea0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 lied buffer. N b
33eb0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 ytes of data are
33ec0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 copied into buf
33ed0 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 fer Z.** from th
33ee0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 e open BLOB, sta
33ef0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 rting at offset
33f00 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a iOffset.)^.**.**
33f10 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 ^If offset iOff
33f20 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e set is less than
33f30 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 N bytes from th
33f40 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f e end of the BLO
33f50 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 B,.** [SQLITE_ER
33f60 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
33f70 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
33f80 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 read. ^If N or
33f90 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 iOffset is.** le
33fa0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 ss than zero, [S
33fb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
33fc0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
33fd0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a data is read..**
33fe0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 ^The size of th
33ff0 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 e blob (and henc
34000 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 e the maximum va
34010 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 lue of N+iOffset
34020 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 ).** can be dete
34030 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 rmined using the
34040 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 [sqlite3_blob_b
34050 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 ytes()] interfac
34060 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 e..**.** ^An att
34070 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f empt to read fro
34080 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c m an expired [BL
34090 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 OB handle] fails
340a0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f with an.** erro
340b0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
340c0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ABORT]..**.**
340d0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 ^(On success, sq
340e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
340f0 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
34100 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 _OK..** Otherwis
34110 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 e, an [error cod
34120 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
34130 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
34140 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
34150 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
34160 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 only works on a
34170 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 [BLOB handle] w
34180 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 hich has been cr
34190 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 eated.** by a pr
341a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
341b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
341c0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 blob_open()] and
341d0 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a which has not.*
341e0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 * been closed by
341f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
34200 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e lose()]. Passin
34210 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e g any other poin
34220 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 ter in.** to thi
34230 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 s routine result
34240 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 s in undefined a
34250 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 nd probably unde
34260 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
34270 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
34280 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f : [sqlite3_blob_
34290 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 write()]..*/.int
342a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 sqlite3_blob_re
342b0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 ad(sqlite3_blob
342c0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 *, void *Z, int
342d0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b N, int iOffset);
342e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
342f0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 : Write Data Int
34300 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 o A BLOB Increme
34310 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 ntally.**.** ^Th
34320 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 is function is u
34330 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 sed to write dat
34340 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b a into an open [
34350 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f BLOB handle] fro
34360 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 m a.** caller-su
34370 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e pplied buffer. ^
34380 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 N bytes of data
34390 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 are copied from
343a0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 the buffer Z.**
343b0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c into the open BL
343c0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
343d0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a offset iOffset..
343e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 **.** ^If the [B
343f0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 LOB handle] pass
34400 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
34410 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 argument was not
34420 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 opened for.** w
34430 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 riting (the flag
34440 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b s parameter to [
34450 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
34460 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a n()] was zero),.
34470 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
34480 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
34490 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a _READONLY]..**.*
344a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
344b0 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 may only modify
344c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 the contents of
344d0 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 the BLOB; it is
344e0 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 .** not possible
344f0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 to increase the
34500 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 size of a BLOB
34510 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a using this API..
34520 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f ** ^If offset iO
34530 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
34540 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
34550 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
34560 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
34570 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
34580 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
34590 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 s written. ^If
345a0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 N is.** less tha
345b0 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 n zero [SQLITE_E
345c0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
345d0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
345e0 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 written..** The
345f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f size of the BLO
34600 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 B (and hence the
34610 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f maximum value o
34620 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 f N+iOffset).**
34630 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 can be determine
34640 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c d using the [sql
34650 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
34660 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
34670 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 .** ^An attempt
34680 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 to write to an e
34690 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e xpired [BLOB han
346a0 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 dle] fails with
346b0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 an.** error code
346c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 of [SQLITE_ABOR
346d0 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 T]. ^Writes to
346e0 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 the BLOB that oc
346f0 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 curred.** before
34700 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
34710 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e e] expired are n
34720 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ot rolled back b
34730 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 y the.** expirat
34740 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c ion of the handl
34750 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 e, though of cou
34760 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 rse those change
34770 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 s might.** have
34780 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e been overwritten
34790 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
347a0 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 t that expired t
347b0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a he BLOB handle.*
347c0 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e * or by other in
347d0 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d dependent statem
347e0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e ents..**.** ^(On
347f0 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 success, sqlite
34800 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 3_blob_write() r
34810 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
34820 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 ..** Otherwise,
34830 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
34840 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 or an [extended
34850 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 error code] is
34860 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a returned.)^.**.*
34870 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f * This routine o
34880 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b nly works on a [
34890 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 BLOB handle] whi
348a0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 ch has been crea
348b0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f ted.** by a prio
348c0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
348d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
348e0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 ob_open()] and w
348f0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 hich has not.**
34900 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b been closed by [
34910 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
34920 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 se()]. Passing
34930 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 any other pointe
34940 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 r in.** to this
34950 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 routine results
34960 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
34970 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
34980 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a rable behavior..
34990 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
349a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
349b0 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ad()]..*/.int sq
349c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
349d0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c (sqlite3_blob *,
349e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 const void *z,
349f0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 int n, int iOffs
34a00 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 et);../*.** CAPI
34a10 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 3REF: Virtual Fi
34a20 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 le System Object
34a30 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 s.**.** A virtua
34a40 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 l filesystem (VF
34a50 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 S) is an [sqlite
34a60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 3_vfs] object.**
34a70 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 that SQLite use
34a80 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a s to interact.**
34a90 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c with the underl
34aa0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
34ab0 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c ystem. Most SQL
34ac0 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 ite builds come
34ad0 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 with a.** single
34ae0 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 default VFS tha
34af0 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 t is appropriate
34b00 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f for the host co
34b10 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 mputer..** New V
34b20 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 FSes can be regi
34b30 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 stered and exist
34b40 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 ing VFSes can be
34b50 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a unregistered..*
34b60 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
34b70 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
34b80 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e rovided..**.** ^
34b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f The sqlite3_vfs_
34ba0 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 find() interface
34bb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
34bc0 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 er to a VFS give
34bd0 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e n its name..** ^
34be0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 Names are case s
34bf0 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 ensitive..** ^Na
34c00 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 mes are zero-ter
34c10 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
34c20 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 rings..** ^If th
34c30 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c ere is no match,
34c40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
34c50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
34c60 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 ^If zVfsName is
34c70 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 NULL then the de
34c80 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 fault VFS is ret
34c90 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 urned..**.** ^Ne
34ca0 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 w VFSes are regi
34cb0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 stered with sqli
34cc0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 te3_vfs_register
34cd0 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 ()..** ^Each new
34ce0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 VFS becomes the
34cf0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 default VFS if
34d00 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 the makeDflt fla
34d10 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 g is set..** ^Th
34d20 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 e same VFS can b
34d30 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
34d40 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
34d50 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e out injury..** ^
34d60 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 To make an exist
34d70 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 ing VFS into the
34d80 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 default VFS, re
34d90 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a gister it again.
34da0 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 ** with the make
34db0 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 Dflt flag set.
34dc0 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 If two different
34dd0 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a VFSes with the.
34de0 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 ** same name are
34df0 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 registered, the
34e00 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
34e10 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a efined. If a.**
34e20 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 VFS is register
34e30 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 ed with a name t
34e40 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 hat is NULL or a
34e50 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a n empty string,.
34e60 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
34e70 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
34e80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 d..**.** ^Unregi
34e90 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 ster a VFS with
34ea0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f the sqlite3_vfs_
34eb0 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 unregister() int
34ec0 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 erface..** ^(If
34ed0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
34ee0 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c is unregistered,
34ef0 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 another VFS is
34f00 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 chosen as.** the
34f10 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 default. The c
34f20 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 hoice for the ne
34f30 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 w VFS is arbitra
34f40 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 ry.)^.*/.sqlite3
34f50 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 _vfs *sqlite3_vf
34f60 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 s_find(const cha
34f70 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e r *zVfsName);.in
34f80 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 t sqlite3_vfs_re
34f90 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 gister(sqlite3_v
34fa0 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c fs*, int makeDfl
34fb0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
34fc0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 vfs_unregister(s
34fd0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f qlite3_vfs*);../
34fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
34ff0 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 utexes.**.** The
35000 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
35010 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 s these routines
35020 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 for thread.** s
35030 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 ynchronization.
35040 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 Though they are
35050 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 intended for int
35060 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 ernal.** use by
35070 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 SQLite, code tha
35080 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
35090 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 SQLite is.** per
350a0 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e mitted to use an
350b0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
350c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 nes..**.** The S
350d0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 QLite source cod
350e0 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 e contains multi
350f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
35100 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 ons.** of these
35110 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 mutex routines.
35120 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 An appropriate
35130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
35140 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 * is selected au
35150 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 tomatically at c
35160 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 ompile-time. ^(
35170 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a The following.**
35180 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
35190 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 are available i
351a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 n the SQLite cor
351b0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
351c0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
351d0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e UTEX_OS2.** <li>
351e0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
351f0 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 PTHREAD.** <li>
35200 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 SQLITE_MUTEX_W
35210 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 32.** <li> SQL
35220 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a ITE_MUTEX_NOOP.*
35230 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
35240 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 ^The SQLITE_MUTE
35250 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 X_NOOP implement
35260 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f ation is a set o
35270 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 f routines.** th
35280 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 at does no real
35290 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 locking and is a
352a0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 ppropriate for u
352b0 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c se in.** a singl
352c0 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 e-threaded appli
352d0 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 cation. ^The SQ
352e0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a LITE_MUTEX_OS2,.
352f0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
35300 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c PTHREAD, and SQL
35310 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d ITE_MUTEX_W32 im
35320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
35330 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 are appropriate
35340 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 for use on OS/2
35350 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 , Unix, and Wind
35360 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ows..**.** ^(If
35370 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
35380 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ed with the SQLI
35390 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 TE_MUTEX_APPDEF
353a0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 preprocessor.**
353b0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 macro defined (w
353c0 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 ith "-DSQLITE_MU
353d0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 TEX_APPDEF=1"),
353e0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a then no mutex.**
353f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35400 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 is included with
35410 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e the library. In
35420 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a this case the.*
35430 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 * application mu
35440 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 st supply a cust
35450 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 om mutex impleme
35460 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 ntation using th
35470 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
35480 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
35490 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 n of the sqlite3
354a0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 _config() functi
354b0 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c on.** before cal
354c0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 ling sqlite3_ini
354d0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 tialize() or any
354e0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 other public sq
354f0 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 lite3_.** functi
35500 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 on that calls sq
35510 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
35520 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ().)^.**.** ^The
35530 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
35540 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 lloc() routine a
35550 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a llocates a new.*
35560 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 * mutex and retu
35570 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
35580 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 it. ^If it retu
35590 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 rns NULL.** that
355a0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 means that a mu
355b0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 tex could not be
355c0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 allocated. ^SQ
355d0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 Lite.** will unw
355e0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e ind its stack an
355f0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f d return an erro
35600 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 r. ^(The argume
35610 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
35620 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 _mutex_alloc() i
35630 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
35640 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
35650 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
35660 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
35670 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 EX_FAST.** <li>
35680 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
35690 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CURSIVE.** <li>
356a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
356b0 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c ATIC_MASTER.** <
356c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
356d0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 X_STATIC_MEM.**
356e0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
356f0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a EX_STATIC_MEM2.*
35700 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35710 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
35720 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
35730 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
35740 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 U.** <li> SQLIT
35750 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
35760 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a RU2.** </ul>)^.*
35770 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
35780 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 two constants (S
35790 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
357a0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 and SQLITE_MUTE
357b0 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 X_RECURSIVE).**
357c0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 cause sqlite3_mu
357d0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 tex_alloc() to c
357e0 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d reate.** a new m
357f0 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 utex. ^The new
35800 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 mutex is recursi
35810 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d ve when SQLITE_M
35820 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
35830 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f * is used but no
35840 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f t necessarily so
35850 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
35860 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e EX_FAST is used.
35870 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d .** The mutex im
35880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 plementation doe
35890 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 s not need to ma
358a0 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e ke a distinction
358b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
358c0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
358d0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 VE and SQLITE_MU
358e0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 TEX_FAST if it d
358f0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
35900 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c to. ^SQLite wil
35910 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 l only request a
35920 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 recursive mutex
35930 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 in.** cases whe
35940 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 re it really nee
35950 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 ds one. ^If a f
35960 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 aster non-recurs
35970 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 ive mutex.** imp
35980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 lementation is a
35990 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 vailable on the
359a0 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 host platform, t
359b0 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 he mutex subsyst
359c0 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 em.** might retu
359d0 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 rn such a mutex
359e0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 in response to S
359f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
35a00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 ..**.** ^The oth
35a10 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d er allowed param
35a20 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 eters to sqlite3
35a30 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 _mutex_alloc() (
35a40 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a anything other.*
35a50 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 * than SQLITE_MU
35a60 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c TEX_FAST and SQL
35a70 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
35a80 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e IVE) each return
35a90 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
35aa0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 a static preexi
35ab0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 sting mutex. ^S
35ac0 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 ix static mutexe
35ad0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 s are.** used by
35ae0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 the current ver
35af0 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 sion of SQLite.
35b00 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
35b10 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 of SQLite.** ma
35b20 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c y add additional
35b30 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e static mutexes.
35b40 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 Static mutexes
35b50 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 are for interna
35b60 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 l.** use by SQLi
35b70 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 te only. Applic
35b80 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 ations that use
35b90 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 SQLite mutexes s
35ba0 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c hould.** use onl
35bb0 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 y the dynamic mu
35bc0 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 texes returned b
35bd0 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 y SQLITE_MUTEX_F
35be0 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 AST or.** SQLITE
35bf0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
35c00 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
35c10 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 at if one of the
35c20 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 dynamic mutex p
35c30 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 arameters (SQLIT
35c40 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 E_MUTEX_FAST.**
35c50 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f or SQLITE_MUTEX_
35c60 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 RECURSIVE) is us
35c70 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ed then sqlite3_
35c80 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a mutex_alloc().**
35c90 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 returns a diffe
35ca0 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 rent mutex on ev
35cb0 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 ery call. ^But
35cc0 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a for the static.*
35cd0 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 * mutex types, t
35ce0 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 he same mutex is
35cf0 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 returned on eve
35d00 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 ry call that has
35d10 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 .** the same typ
35d20 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 e number..**.**
35d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 ^The sqlite3_mut
35d40 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e ex_free() routin
35d50 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 e deallocates a
35d60 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c previously.** al
35d70 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 located dynamic
35d80 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 mutex. ^SQLite
35d90 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 is careful to de
35da0 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a allocate every.*
35db0 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 * dynamic mutex
35dc0 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 that it allocate
35dd0 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 s. The dynamic
35de0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 mutexes must not
35df0 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 be in.** use wh
35e00 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c en they are deal
35e10 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 located. Attemp
35e20 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 ting to dealloca
35e30 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d te a static.** m
35e40 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 utex results in
35e50 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
35e60 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 or. ^SQLite nev
35e70 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a er deallocates.*
35e80 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 * a static mutex
35e90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
35ea0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
35eb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d () and sqlite3_m
35ec0 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 utex_try() routi
35ed0 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 nes attempt.** t
35ee0 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e o enter a mutex.
35ef0 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 ^If another th
35f00 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 read is already
35f10 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 within the mutex
35f20 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 ,.** sqlite3_mut
35f30 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 ex_enter() will
35f40 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 block and sqlite
35f50 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 3_mutex_try() wi
35f60 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ll return.** SQL
35f70 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 ITE_BUSY. ^The
35f80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
35f90 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 y() interface re
35fa0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
35fb0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 ].** upon succes
35fc0 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d sful entry. ^(M
35fd0 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 utexes created u
35fe0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d sing.** SQLITE_M
35ff0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 UTEX_RECURSIVE c
36000 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 an be entered mu
36010 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 ltiple times by
36020 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e the same thread.
36030 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 .** In such case
36040 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 s the,.** mutex
36050 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 must be exited a
36060 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f n equal number o
36070 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 f times before a
36080 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a nother thread.**
36090 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e can enter.)^ ^
360a0 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 (If the same thr
360b0 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 ead tries to ent
360c0 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 er any other.**
360d0 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f kind of mutex mo
360e0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 re than once, th
360f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
36100 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 defined..** SQLi
36110 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 te will never ex
36120 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 hibit.** such be
36130 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 havior in its ow
36140 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 n use of mutexes
36150 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 .)^.**.** ^(Some
36160 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 systems (for ex
36170 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 ample, Windows 9
36180 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 5) do not suppor
36190 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a t the operation.
361a0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 ** implemented b
361b0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f y sqlite3_mutex_
361c0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 try(). On those
361d0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 systems, sqlite
361e0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 3_mutex_try().**
361f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
36200 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e urn SQLITE_BUSY.
36210 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
36220 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 e only ever uses
36230 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
36240 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 x_try() as an op
36250 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 timization so th
36260 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 is is acceptable
36270 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a behavior.)^.**.
36280 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36290 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f mutex_leave() ro
362a0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 utine exits a mu
362b0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 tex that was.**
362c0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 previously enter
362d0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 ed by the same t
362e0 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 hread. ^(The b
362f0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e ehavior.** is un
36300 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d defined if the m
36310 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 utex is not curr
36320 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 ently entered by
36330 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 the.** calling
36340 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 thread or is not
36350 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 currently alloc
36360 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 ated. SQLite wi
36370 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 ll.** never do e
36380 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ither.)^.**.** ^
36390 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
363a0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
363b0 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 _enter(), sqlite
363c0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 3_mutex_try(), o
363d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 r.** sqlite3_mut
363e0 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 ex_leave() is a
363f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
36400 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 en all three rou
36410 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 tines.** behave
36420 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a as no-ops..**.**
36430 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
36440 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
36450 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d ] and [sqlite3_m
36460 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e utex_notheld()].
36470 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 .*/.sqlite3_mute
36480 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 x *sqlite3_mutex
36490 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 _alloc(int);.voi
364a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
364b0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 free(sqlite3_mut
364c0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ex*);.void sqlit
364d0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 e3_mutex_enter(s
364e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
364f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
36500 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 x_try(sqlite3_mu
36510 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 tex*);.void sqli
36520 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
36530 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
36540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36550 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 : Mutex Methods
36560 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 Object.**.** An
36570 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
36580 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e structure defin
36590 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c es the low-level
365a0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 routines.** use
365b0 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e d to allocate an
365c0 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a d use mutexes..*
365d0 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 *.** Usually, th
365e0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
365f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
36600 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 provided by SQLi
36610 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 te are.** suffic
36620 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 ient, however th
36630 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f e user has the o
36640 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 ption of substit
36650 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a uting a custom.*
36660 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
36670 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 for specialized
36680 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 deployments or
36690 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 systems for whic
366a0 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 h SQLite.** does
366b0 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 not provide a s
366c0 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
366d0 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 tation. In this
366e0 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a case, the user.*
366f0 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f * creates and po
36700 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 pulates an insta
36710 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
36720 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a cture to pass.**
36730 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
36740 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 ig() along with
36750 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
36760 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e IG_MUTEX] option
36770 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c ..** Additionall
36780 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f y, an instance o
36790 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
367a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
367b0 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 an.** output var
367c0 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 iable when query
367d0 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 ing the system f
367e0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d or the current m
367f0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
36800 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 tation, using th
36810 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
36820 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f _GETMUTEX] optio
36830 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d n..**.** ^The xM
36840 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 utexInit method
36850 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 defined by this
36860 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 structure is inv
36870 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 oked as.** part
36880 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 of system initia
36890 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 lization by the
368a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
368b0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ze() function..*
368c0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 * ^The xMutexIni
368d0 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c t routine is cal
368e0 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 le by SQLite exa
368f0 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 ctly once for ea
36900 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 ch.** effective
36910 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
36920 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a _initialize()]..
36930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 **.** ^The xMute
36940 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 xEnd method defi
36950 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 ned by this stru
36960 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 cture is invoked
36970 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 as.** part of s
36980 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 ystem shutdown b
36990 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 y the sqlite3_sh
369a0 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f utdown() functio
369b0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d n. The.** implem
369c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 entation of this
369d0 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 method is expec
369e0 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 ted to release a
369f0 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a ll outstanding.*
36a00 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 * resources obta
36a10 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 ined by the mute
36a20 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d x methods implem
36a30 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 entation, especi
36a40 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 ally.** those ob
36a50 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d tained by the xM
36a60 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e utexInit method.
36a70 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 ^The xMutexEnd
36a80 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
36a90 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 is invoked exact
36aa0 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ly once for each
36ab0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
36ac0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
36ad0 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 *.** ^(The remai
36ae0 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f ning seven metho
36af0 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 ds defined by th
36b00 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d is structure (xM
36b10 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d utexAlloc,.** xM
36b20 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 utexFree, xMutex
36b30 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 Enter, xMutexTry
36b40 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 , xMutexLeave, x
36b50 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a MutexHeld and.**
36b60 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 xMutexNotheld)
36b70 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f implement the fo
36b80 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
36b90 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 es (respectively
36ba0 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ):.**.** <ul>.**
36bb0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
36bc0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
36bd0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
36be0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
36bf0 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a _free()] </li>.*
36c00 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
36c10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
36c20 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
36c30 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
36c40 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a x_try()] </li>.*
36c50 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
36c60 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 e3_mutex_leave()
36c70 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
36c80 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
36c90 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a x_held()] </li>.
36ca0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
36cb0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
36cc0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f d()] </li>.** </
36cd0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ul>)^.**.** The
36ce0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 only difference
36cf0 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c is that the publ
36d00 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 ic sqlite3_XXX f
36d10 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 unctions enumera
36d20 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c ted.** above sil
36d30 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 ently ignore any
36d40 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 invocations tha
36d50 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f t pass a NULL po
36d60 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a inter instead.**
36d70 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 of a valid mute
36d80 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d x handle. The im
36d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
36da0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 the methods def
36db0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 ined.** by this
36dc0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f structure are no
36dd0 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 t required to ha
36de0 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 ndle this case,
36df0 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f the results.** o
36e00 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c f passing a NULL
36e10 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 pointer instead
36e20 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 of a valid mute
36e30 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 x handle are und
36e40 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 efined.** (i.e.
36e50 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 it is acceptable
36e60 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 to provide an i
36e70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 mplementation th
36e80 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a at segfaults if.
36e90 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20 ** it is passed
36ea0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e a NULL pointer).
36eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 .**.** The xMute
36ec0 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d xInit() method m
36ed0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 ust be threadsaf
36ee0 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20 e. ^It must be
36ef0 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 harmless to.** i
36f00 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 nvoke xMutexInit
36f10 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 () mutiple times
36f20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
36f30 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 process and wit
36f40 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e hout.** interven
36f50 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 ing calls to xMu
36f60 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e texEnd(). Secon
36f70 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
36f80 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 calls to.** xMu
36f90 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 texInit() must b
36fa0 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 e no-ops..**.**
36fb0 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 ^xMutexInit() mu
36fc0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 st not use SQLit
36fd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
36fe0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 ion ([sqlite3_ma
36ff0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 lloc()].** and i
37000 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 ts associates).
37010 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 ^Similarly, xMu
37020 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 texAlloc() must
37030 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d not use SQLite m
37040 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
37050 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 ion for a static
37060 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 mutex. ^Howeve
37070 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 r xMutexAlloc()
37080 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a may use SQLite.*
37090 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
370a0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f ion for a fast o
370b0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 r recursive mute
370c0 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 x..**.** ^SQLite
370d0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 will invoke the
370e0 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 xMutexEnd() met
370f0 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 hod when [sqlite
37100 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 3_shutdown()] is
37110 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 .** called, but
37120 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f only if the prio
37130 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 r call to xMutex
37140 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 Init returned SQ
37150 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 LITE_OK..** If x
37160 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 MutexInit fails
37170 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 in any way, it i
37180 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c s expected to cl
37190 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 ean up after its
371a0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 elf.** prior to
371b0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 returning..*/.ty
371c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
371d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
371e0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ds sqlite3_mutex
371f0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
37200 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
37210 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 ethods {. int (
37220 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 *xMutexInit)(voi
37230 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 d);. int (*xMut
37240 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 exEnd)(void);.
37250 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 sqlite3_mutex *(
37260 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e *xMutexAlloc)(in
37270 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 t);. void (*xMu
37280 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 texFree)(sqlite3
37290 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 _mutex *);. voi
372a0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 d (*xMutexEnter)
372b0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
372c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
372d0 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 xTry)(sqlite3_mu
372e0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
372f0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 *xMutexLeave)(sq
37300 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
37310 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 int (*xMutexHe
37320 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
37330 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
37340 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c utexNotheld)(sql
37350 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d ite3_mutex *);.}
37360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37370 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 F: Mutex Verific
37380 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a ation Routines.*
37390 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
373a0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e _mutex_held() an
373b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
373c0 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e notheld() routin
373d0 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 es.** are intend
373e0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 ed for use insid
373f0 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 e assert() state
37400 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c ments. ^The SQL
37410 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 ite core.** neve
37420 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 r uses these rou
37430 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 tines except ins
37440 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 ide an assert()
37450 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 and applications
37460 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 .** are advised
37470 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 to follow the le
37480 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 ad of the core.
37490 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 ^The SQLite cor
374a0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 e only.** provid
374b0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f es implementatio
374c0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 ns for these rou
374d0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 tines when it is
374e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
374f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 h the SQLITE_DEB
37500 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 UG flag. ^Exter
37510 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d nal mutex implem
37520 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 entations.** are
37530 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 only required t
37540 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 o provide these
37550 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 routines if SQLI
37560 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 TE_DEBUG is.** d
37570 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 efined and if ND
37580 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 EBUG is not defi
37590 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ned..**.** ^Thes
375a0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c e routines shoul
375b0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 d return true if
375c0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 the mutex in th
375d0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 eir argument.**
375e0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 is held or not h
375f0 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c eld, respectivel
37600 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e y, by the callin
37610 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 g thread..**.**
37620 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ^The implementat
37630 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 ion is not requi
37640 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 red to provided
37650 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 versions of thes
37660 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 e.** routines th
37670 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b at actually work
37680 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 . If the impleme
37690 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
376a0 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 provide working
376b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
376c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
376d0 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 it should at lea
376e0 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 st provide stubs
376f0 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 that always.**
37700 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 return true so t
37710 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 hat one does not
37720 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 get spurious as
37730 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 sertion failures
37740 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
37750 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
37760 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
37770 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
37780 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 er then.** the r
37790 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 outine should re
377a0 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73 turn 1. This s
377b0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 eems counter-int
377c0 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 uitive since.**
377d0 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 clearly the mute
377e0 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 x cannot be held
377f0 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 if it does not
37800 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a exist. But the.
37810 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 ** the reason th
37820 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 e mutex does not
37830 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 exist is becaus
37840 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e e the build is n
37850 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 ot.** using mute
37860 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 xes. And we do
37870 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 not want the ass
37880 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 ert() containing
37890 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 the.** call to
378a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
378b0 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f ld() to fail, so
378c0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 a non-zero retu
378d0 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 rn is.** the app
378e0 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 ropriate thing t
378f0 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 o do. ^The sqli
37900 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
37910 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 d().** interface
37920 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 should also ret
37930 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e urn 1 when given
37940 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
37950 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 .*/.#ifndef NDEB
37960 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d UG.int sqlite3_m
37970 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 utex_held(sqlite
37980 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
37990 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
379a0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 held(sqlite3_mut
379b0 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a ex*);.#endif../*
379c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
379d0 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 tex Types.**.**
379e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 The [sqlite3_mut
379f0 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 ex_alloc()] inte
37a00 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 rface takes a si
37a10 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a ngle argument.**
37a20 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 which is one of
37a30 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 these integer c
37a40 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 onstants..**.**
37a50 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 The set of stati
37a60 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 c mutexes may ch
37a70 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 ange from one SQ
37a80 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 Lite release to
37a90 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 the.** next. Ap
37aa0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
37ab0 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 override the bui
37ac0 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 lt-in mutex logi
37ad0 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 c must be.** pre
37ae0 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f pared to accommo
37af0 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 date additional
37b00 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a static mutexes..
37b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
37b20 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 E_MUTEX_FAST
37b30 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
37b40 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
37b50 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
37b60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
37b70 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
37b80 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 ASTER 2.#defi
37b90 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
37ba0 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 STATIC_MEM
37bb0 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 3 /* sqlite3_m
37bc0 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 alloc() */.#defi
37bd0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
37be0 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 STATIC_MEM2
37bf0 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 4 /* NOT USED
37c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
37c10 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f E_MUTEX_STATIC_O
37c20 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 PEN 4 /* s
37c30 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 qlite3BtreeOpen(
37c40 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
37c50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37c60 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a _PRNG 5 /*
37c70 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 sqlite3_random(
37c80 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
37c90 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37ca0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a _LRU 6 /*
37cb0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a lru page list *
37cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
37cd0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
37ce0 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 U2 7 /* lr
37cf0 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a u page list */..
37d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37d10 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 Retrieve the mut
37d20 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 ex for a databas
37d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a e connection.**.
37d40 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 ** ^This interfa
37d50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
37d60 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 nter the [sqlite
37d70 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 3_mutex] object
37d80 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 that .** seriali
37d90 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68 zes access to th
37da0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37db0 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e ection] given in
37dc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
37dd0 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61 when the [threa
37de0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 ding mode] is Se
37df0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66 rialized..** ^If
37e00 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
37e10 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d mode] is Single-
37e20 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d thread or Multi-
37e30 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 thread then this
37e40 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
37e50 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
37e60 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d er..*/.sqlite3_m
37e70 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 utex *sqlite3_db
37e80 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 _mutex(sqlite3*)
37e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37ea0 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e F: Low-Level Con
37eb0 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 trol Of Database
37ec0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 Files.**.** ^Th
37ed0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
37ee0 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
37ef0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 face makes a dir
37f00 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a ect call to the.
37f10 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 ** xFileControl
37f20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b method for the [
37f30 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
37f40 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 ds] object assoc
37f50 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 iated.** with a
37f60 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
37f70 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 ase identified b
37f80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 y the second arg
37f90 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e ument. ^The.** n
37fa0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
37fb0 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 74 ase "main" for t
37fc0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
37fd0 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 74 or "temp" for t
37fe0 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 62 he.** TEMP datab
37ff0 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65 ase, or the name
38000 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 66 that appears af
38010 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f ter the AS keywo
38020 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 rd for.** databa
38030 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 64 ses that are add
38040 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 54 ed using the [AT
38050 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e TACH] SQL comman
38060 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 6f d..** ^A NULL po
38070 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 65 inter can be use
38080 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d d in place of "m
38090 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 6f ain" to refer to
380a0 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 74 the.** main dat
380b0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 5e abase file..** ^
380c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
380d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
380e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a to this routine.
380f0 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 ** are passed di
38100 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 rectly through t
38110 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 o the second and
38120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
38130 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c s of.** the xFil
38140 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e eControl method.
38150 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 ^The return va
38160 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 lue of the xFile
38170 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f Control.** metho
38180 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 d becomes the re
38190 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
381a0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a is routine..**.*
381b0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 * ^If the second
381c0 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e parameter (zDbN
381d0 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 ame) does not ma
381e0 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 tch the name of
381f0 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 any.** open data
38200 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 base file, then
38210 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 SQLITE_ERROR is
38220 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 73 returned. ^This
38230 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
38240 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 s not remembered
38250 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 and will not be
38260 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 recalled by [sq
38270 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
38280 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
38290 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20 errmsg()]. The
382a0 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 underlying xFile
382b0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d Control method m
382c0 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 ight.** also ret
382d0 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 urn SQLITE_ERROR
382e0 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 . There is no w
382f0 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 ay to distinguis
38300 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 h between.** an
38310 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d incorrect zDbNam
38320 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f e and an SQLITE_
38330 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f ERROR return fro
38340 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 m the underlying
38350 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c .** xFileControl
38360 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53 method..**.** S
38370 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
38380 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
38390 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
383a0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 _file_control(sq
383b0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
383c0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 ar *zDbName, int
383d0 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a op, void*);../*
383e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
383f0 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 0a sting Interface.
38400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
38410 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 e3_test_control(
38420 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
38430 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 sed to read out
38440 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 internal.** stat
38450 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 e of SQLite and
38460 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 to inject faults
38470 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 into SQLite for
38480 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 testing.** purp
38490 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 73 oses. ^The firs
384a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
384b0 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 n operation code
384c0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 that determines
384d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 .** the number,
384e0 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 meaning, and ope
384f0 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 ration of all su
38500 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 bsequent paramet
38510 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ers..**.** This
38520 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
38530 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c for use by appl
38540 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 ications. It ex
38550 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 ists solely.** f
38560 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65 or verifying the
38570 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69 correct operati
38580 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 on of the SQLite
38590 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e library. Depen
385a0 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 ding.** on how t
385b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
385c0 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 y is compiled, t
385d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69 his interface mi
385e0 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a ght not exist..*
385f0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
38600 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f of the operatio
38610 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d n codes, their m
38620 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72 eanings, the par
38630 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 ameters.** they
38640 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74 take, and what t
38650 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 hey do are all s
38660 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
38670 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e without notice.
38680 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 .** Unlike most
38690 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 of the SQLite AP
386a0 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e I, this function
386b0 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
386c0 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 ed to.** operate
386d0 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 consistently fr
386e0 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 om one release t
386f0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 o the next..*/.i
38700 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f nt sqlite3_test_
38710 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 control(int op,
38720 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
38730 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 I3REF: Testing I
38740 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 nterface Operati
38750 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 on Codes.**.** T
38760 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
38770 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 re the valid ope
38780 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 ration code para
38790 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 meters used.** a
387a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
387b0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
387c0 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d _test_control()]
387d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 ..**.** These pa
387e0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 rameters and the
387f0 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 ir meanings are
38800 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
38810 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 e.** without not
38820 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 ice. These valu
38830 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 es are for testi
38840 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 ng purposes only
38850 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
38860 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 s should not use
38870 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 any of these pa
38880 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a rameters or the.
38890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 ** [sqlite3_test
388a0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
388b0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e rface..*/.#defin
388c0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54