0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 ent system. ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d ERSION "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 ID "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a . ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 nterfaces match
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 g constant. The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 e DLL. ^The.**
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 tion returns an
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 ION_NUMBER]. ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 constant whose
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 acro..**.** See
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 ceid(void);.int
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 * compile time.
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 d(). .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 erating.** over
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 on string. ^If
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 compile_options
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 OptName);.const
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 eadsafe. When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 READSAFE] macro
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 d. Without the
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 ently from more
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 .**.** Enabling
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 .** So if speed
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 s. But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 THREADSAFE=1 or
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 =2 then mutexes
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ()].** with the
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e ONFIG_MUTEX]. ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 se()].** is its
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 * Because there
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 defs for 64-bit
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 preferred type
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 definitions..**
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a clusive. ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 s .** between 0
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 use a lot of C
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 interface runs
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 st.** argument.
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 ments. ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 ough to the 1st
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 ocation. ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 ipped. ^If the
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ning..**.** ^If
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ns SQLITE_ABORT
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 ult. ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e . ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 lback is a NULL
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 pointer. ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 ntry represents
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 comments, then
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 s are evaluated
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c ** is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 ent text passed
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 into.** the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **errmsg
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 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 44 61 74 61 62 61 73 65 20 6c 6f 63 6b /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 ** [SQLITE_OK |
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 may expect the
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f * over time. So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ew result codes
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 nded. It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 R_READ
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 _SHORT_READ
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 SYNC
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 NCATE (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 T (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 K (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 TE_IOERR_NOMEM
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 TE_IOERR_LOCK
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 TE_IOERR_CLOSE
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 SE (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 CACHE (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c TE_LOCKED | (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c Y (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 ITE_BUSY | (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 TEMPDIR (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 001 /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 002 /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 TE_OPEN_CREATE
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 004 /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 CLOSE 0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 008 /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 010 /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 Y 0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 020 /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 TE_OPEN_MAIN_DB
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 100 /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 TE_OPEN_TEMP_DB
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 200 /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 T_DB 0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 400 /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 RNAL 0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 800 /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 RNAL 0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 AL 0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 OURNAL 0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 TE_OPEN_NOMUTEX
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 X 0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 CHE 0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 ACHE 0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 TE_OPEN_WAL
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 IC
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 AP_ATOMIC512
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 1K
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 _ATOMIC2K
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 TOMIC8K
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 0000040.#define
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 MIC32K
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 CAP_ATOMIC64K
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 APPEND
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 ABLE_WHEN_OPEN
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 s a combination
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 at means to use
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 emantics..** If
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a of fsync()..**.
6040: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 ** Do not confus
6050: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e e the SQLITE_SYN
6060: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
6070: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
6080: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ags.** with the
6090: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
60a0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 ous]=NORMAL and
60b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
60c0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 ous]=FULL.** set
60d0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e tings. The [syn
60e0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d chronous pragma]
60f0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e determines when
6100: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a calls to the.**
6110: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f xSync VFS metho
6120: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c d occur and appl
6130: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 ies uniformly ac
6140: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 ross all platfor
6150: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 ms..** The SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e E_SYNC_NORMAL an
6170: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 d SQLITE_SYNC_FU
6180: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 LL flags determi
6190: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 ne how.** energe
61a0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 tic or rigorous
61b0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 or forceful the
61c0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 sync operations
61d0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 are and.** only
61e0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 make a differenc
61f0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 e on Mac OSX for
6200: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c the default SQL
6210: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 ite code..** (Th
6220: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d ird-party VFS im
6230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 plementations mi
6240: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 ght also make th
6250: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a e distinction.**
6260: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f between SQLITE_
6270: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6290: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a , but among the.
62a0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ** operating sys
62b0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 tems natively su
62c0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
62d0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a e, only Mac OSX.
62e0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 ** cares about t
62f0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a he difference.).
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 E_SYNC_NORMAL
6320: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 0x00002.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
6340: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 _FULL 0
6350: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 x00003.#define S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
6370: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 NLY 0x00010
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6390: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
63a0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a pen File Handle.
63b0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 **.** An [sqlite
63c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 3_file] object r
63d0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
63e0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a n file in the .*
63f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c * [sqlite3_vfs |
6400: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
6410: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 yer]. Individua
6420: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a l OS interface.*
6430: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
6440: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
6450: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
6460: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
6470: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
6480: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ields.** for the
6490: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 ir own use. The
64a0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 pMethods entry
64b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
64c0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
64d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
64e0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d t that defines m
64f0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f ethods for perfo
6500: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 rming.** I/O ope
6510: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f rations on the o
6520: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 pen file..*/.typ
6530: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
6540: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 te3_file sqlite3
6550: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 _file;.struct sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 lite3_file {. c
6570: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 onst struct sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a te3_io_methods *
6590: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 pMethods; /* Me
65a0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 thods for an ope
65b0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a n file */.};../*
65c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
65d0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 Interface File
65e0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 Virtual Methods
65f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 Object.**.** Eve
6600: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
6610: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
6620: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 fs] xOpen method
6630: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
6640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
6650: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
6660: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
6670: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
6680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
6690: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
66a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
66b0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
66c0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
66d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
66e0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
66f0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
6700: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
6710: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
6720: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
6730: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
6740: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
6750: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e .** If the xOpen
6760: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 method sets the
6770: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
6780: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a ethods element .
6790: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ** to a non-NULL
67a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 pointer, then t
67b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 he sqlite3_io_me
67c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 thods.xClose met
67d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e hod.** may be in
67e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 voked even if th
67f0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 e xOpen reported
6800: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e that it failed.
6810: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 The.** only wa
6820: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 y to prevent a c
6830: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f all to xClose fo
6840: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 llowing a failed
6850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 xOpen.** is for
6860: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 the xOpen to se
6870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
6880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
6890: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ent to NULL..**.
68a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
68b0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d ument to xSync m
68c0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 ay be one of [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
68e0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
68f0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 SYNC_FULL]. The
6900: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 first choice is
6910: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e the normal fsyn
6920: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f c()..** The seco
6930: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d nd choice is a M
6940: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
6950: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 llsync. The [SQ
6960: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
6970: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 LY].** flag may
6980: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e be ORed in to in
6990: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 dicate that only
69a0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 the data of the
69b0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 file.** and not
69c0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 its inode needs
69d0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a to be synced..*
69e0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 *.** The integer
69f0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b values to xLock
6a00: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6a10: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c are one of.** <
6a20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
6a30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a ITE_LOCK_NONE],.
6a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6a50: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
6a70: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a CK_RESERVED],.**
6a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
6a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a CK_PENDING], or.
6aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6ab0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e LOCK_EXCLUSIVE].
6ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f .** </ul>.** xLo
6ad0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 ck() increases t
6ae0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b he lock. xUnlock
6af0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 () decreases the
6b00: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 lock..** The xC
6b10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
6b20: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 () method checks
6b30: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 whether any dat
6b40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
6b50: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 ,.** either in t
6b60: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 his process or i
6b70: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f n some other pro
6b80: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 cess, is holding
6b90: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 a RESERVED,.**
6ba0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c PENDING, or EXCL
6bb0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 USIVE lock on th
6bc0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 e file. It retu
6bd0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 rns true.** if s
6be0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 uch a lock exist
6bf0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 s and false othe
6c00: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rwise..**.** The
6c10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
6c20: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 method is a gene
6c30: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 ric interface th
6c40: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d at allows custom
6c50: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e .** VFS implemen
6c60: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 tations to direc
6c70: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f tly control an o
6c80: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 pen file using t
6c90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
6ca0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
6cb0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 nterface. The s
6cc0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d econd "op" argum
6cd0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 ent is an.** int
6ce0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 eger opcode. Th
6cf0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
6d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f is a generic po
6d10: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 inter intended t
6d20: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 o.** point to a
6d30: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d structure that m
6d40: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d ay contain argum
6d50: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e ents or space in
6d60: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 which to.** wri
6d70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 te return values
6d80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 . Potential use
6d90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 s for xFileContr
6da0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a ol() might be.**
6db0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e functions to en
6dc0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f able blocking lo
6dd0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 cks with timeout
6de0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 s, to change the
6df0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 .** locking stra
6e00: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c tegy (for exampl
6e10: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c e to use dot-fil
6e20: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 e locks), to inq
6e30: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 uire.** about th
6e40: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f e status of a lo
6e50: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 ck, or to break
6e60: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 stale locks. Th
6e70: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 e SQLite.** core
6e80: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 reserves all op
6e90: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 codes less than
6ea0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 100 for its own
6eb0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 use..** A [SQLIT
6ec0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
6ed0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f E | list of opco
6ee0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 des] less than 1
6ef0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 00 is available.
6f00: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
6f10: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 that define a c
6f20: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 ustom xFileContr
6f30: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 ol method should
6f40: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 use opcodes.**
6f50: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 greater than 100
6f60: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 to avoid confli
6f70: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 cts..**.** The x
6f80: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 SectorSize() met
6f90: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 hod returns the
6fa0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 sector size of t
6fb0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 he.** device tha
6fc0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 t underlies the
6fd0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f file. The secto
6fe0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a r size is the.**
6ff0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 minimum write t
7000: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f hat can be perfo
7010: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 rmed without dis
7020: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 turbing.** other
7030: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
7040: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 le. The xDevice
7050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 Characteristics(
7060: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
7070: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 rns a bit vector
7080: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 describing beha
7090: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 viors of the.**
70a0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 underlying devic
70b0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
70c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c CAP_ATOMIC].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 P_ATOMIC512].**
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 AP_ATOMIC1K].**
7120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7130: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 AP_ATOMIC2K].**
7140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7150: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 AP_ATOMIC4K].**
7160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7170: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 AP_ATOMIC8K].**
7180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7190: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a AP_ATOMIC16K].**
71a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
71b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a CAP_ATOMIC32K].*
71c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
71d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a OCAP_ATOMIC64K].
71e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
7200: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 D].** <li> [SQLI
7210: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
7220: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IAL].** </ul>.**
7230: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
7240: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
7250: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
7260: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
7270: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
7280: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
7290: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
72a0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
72b0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
72c0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
72d0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
72e0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
72f0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
7300: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
7310: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
7320: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
7330: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
7340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
7350: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
7360: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
7370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
7380: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
7390: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
73a0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
73c0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
73d0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
73e0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
73f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
7410: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
7420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
7430: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
7440: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
7450: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
7460: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a xWrite()..**.**
7470: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 If xRead() retu
7480: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 rns SQLITE_IOERR
7490: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d _SHORT_READ it m
74a0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a ust also fill.**
74b0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 in the unread p
74c0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ortions of the b
74d0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 uffer with zeros
74e0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a . A VFS that.**
74f0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 fails to zero-f
7500: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
7510: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f might seem to wo
7520: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a rk. However,.**
7530: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f failure to zero
7540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
7550: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
7560: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 y lead to.** dat
7570: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e abase corruption
7580: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
7590: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
75a0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 ethods sqlite3_i
75b0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 o_methods;.struc
75c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
75d0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 hods {. int iVe
75e0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
75f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 Close)(sqlite3_f
7600: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
7610: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 Read)(sqlite3_fi
7620: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 le*, void*, int
7630: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
7640: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
7650: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
7660: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
7670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
7690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
76a0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
76b0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
76c0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 3_int64 size);.
76d0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
76e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
76f0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 flags);. int (
7700: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 *xFileSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
7720: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 e3_int64 *pSize)
7730: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 ;. int (*xLock)
7740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
7750: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 int);. int (*xU
7760: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 nlock)(sqlite3_f
7770: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
7780: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 t (*xCheckReserv
7790: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f edLock)(sqlite3_
77a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 file*, int *pRes
77b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
77c0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 ileControl)(sqli
77d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f te3_file*, int o
77e0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a p, void *pArg);.
77f0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 int (*xSectorS
7800: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
7810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 e*);. int (*xDe
7820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
7830: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ics)(sqlite3_fil
7840: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 e*);. /* Method
7850: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
7860: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 d for version 1
7870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d */. int (*xShmM
7880: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
7890: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 *, int iPg, int
78a0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 pgsz, int, void
78b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 volatile**);. i
78c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 nt (*xShmLock)(s
78d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
78e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c t offset, int n,
78f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 int flags);. v
7900: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 oid (*xShmBarrie
7910: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a r)(sqlite3_file*
7920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 );. int (*xShmU
7930: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 nmap)(sqlite3_fi
7940: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 le*, int deleteF
7950: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f lag);. /* Metho
7960: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
7970: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 id for version 2
7980: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f */. /* Additio
7990: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 nal methods may
79a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
79b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d re releases */.}
79c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
79d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 F: Standard File
79e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 Control Opcodes
79f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
7a00: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 eger constants a
7a10: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 re opcodes for t
7a20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
7a30: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 method.** of the
7a40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
7a50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 hods] object and
7a60: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
7a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
7a80: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a ].** interface..
7a90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
7ab0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
7ac0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
7ad0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
7ae0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
7af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
7b00: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
7b10: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
7b20: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
7b40: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
7b50: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
7b60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
7b70: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
7b80: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
7b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
7ba0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
7bb0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
7bc0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
7bd0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
7be0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
7bf0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
7c00: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c testing and onl
7c10: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 y needs to be su
7c20: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c pported when SQL
7c30: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 ITE_TEST.** is d
7c40: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
7c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 SIZE_HINT] opcod
7c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c e is used by SQL
7c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 ite to give the
7c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 VFS.** layer a h
7ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 int of how large
7cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
7cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 le will grow to
7cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a be during the.**
7ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 current transac
7cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 tion. This hint
7d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
7d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 ed to be accurat
7d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f e but it.** is o
7d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 ften close. The
7d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 underlying VFS
7d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 might choose to
7d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 preallocate data
7d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 base.** file spa
7d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 ce based on this
7d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 hint in order t
7da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f o help writes to
7db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
7dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 file run faster
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
7de0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
7df0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
7e00: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
7e10: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
7e20: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
7e30: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
7e40: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
7e50: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
7e60: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
7e70: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
7e80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
7ea0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
7eb0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
7ec0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
7ed0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
7ee0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
7ef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
7f00: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
7f10: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
7f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
7f30: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
7f40: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
7f50: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
7f60: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
7f70: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
7f80: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
7f90: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
7fa0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 me systems..*/.#
7fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
7fc0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
7fd0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
7fe0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
7ff0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 OXYFILE 2.#
8000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
8010: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
8020: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
8030: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
8040: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
8050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
8060: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
8070: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
8080: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
8090: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23 K_SIZE 6.#
80a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
80b0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
80c0: 20 20 20 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43 7.../*.** C
80d0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
80e0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
80f0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
8100: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
8110: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
8120: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
8130: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
8140: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
8150: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
8160: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
8170: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
8180: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
8190: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
81a0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
81b0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
81c0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
81d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
81e0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
81f0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
8200: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
8210: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
8220: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
8230: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
8240: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
8250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
8260: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
8270: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
8280: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
8290: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
82a0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
82b0: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
82c0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
82d0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
82e0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
82f0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
8300: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
8310: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
8320: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
8330: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a file system"..*
8340: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
8350: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
8360: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
8370: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
8380: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
8390: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
83a0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
83b0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
83c0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
83d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
83e0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
83f0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
8400: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
8410: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
8420: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
8430: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
8440: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
8450: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
8460: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
8470: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
8480: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
8490: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
84a0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
84b0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
84c0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
84d0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
84e0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
84f0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
8500: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
8510: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
8520: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
8530: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
8540: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
8550: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
8560: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
8570: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
8580: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
8590: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
85a0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
85b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
85c0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
85d0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
85e0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
85f0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
8600: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
8610: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
8620: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
8630: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
8640: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
8650: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
8660: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
8670: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
8680: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
8690: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
86a0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
86b0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
86c0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
86d0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
86e0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
86f0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
8700: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
8710: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
8720: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
8730: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
8740: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
8750: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
8760: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
8770: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
8780: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
8790: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
87a0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
87b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
87c0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
87d0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
87e0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
87f0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
8800: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
8810: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
8820: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
8830: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
8840: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
8850: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
8860: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
8870: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
8880: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
8890: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
88a0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
88b0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
88c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
88d0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
88e0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
88f0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
8900: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
8910: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
8920: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
8930: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
8940: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
8950: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
8960: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
8970: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
8980: 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 0 alphanumeric a
8990: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
89a0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
89b0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
89c0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
89d0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
89e0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
89f0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
8a00: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
8a10: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
8a20: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
8a30: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
8a40: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
8a50: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
8a60: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
8a70: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
8a80: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
8a90: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
8aa0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
8ab0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
8ac0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
8ad0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
8ae0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
8af0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
8b00: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
8b10: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
8b20: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
8b30: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
8b40: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
8b50: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
8b60: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
8b70: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
8b80: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
8b90: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
8ba0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
8bb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
8bc0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
8bd0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
8be0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
8bf0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
8c00: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
8c10: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
8c20: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
8c30: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
8c40: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
8c50: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
8c60: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
8c70: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
8c80: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
8c90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
8ca0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
8cb0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
8cc0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
8cd0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
8ce0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
8cf0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
8d00: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
8d10: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
8d20: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
8d30: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
8d40: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
8d50: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
8d60: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
8d70: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
8d80: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
8d90: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
8da0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
8db0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
8dc0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
8dd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8de0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
8df0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
8e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
8e10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
8e20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
8e30: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
8e40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
8e50: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
8e60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
8e70: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
8e80: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
8e90: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
8ea0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
8eb0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
8ec0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
8ed0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
8ee0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
8ef0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
8f00: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
8f10: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
8f20: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
8f30: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
8f40: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
8f50: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
8f60: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
8f70: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
8f80: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
8f90: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
8fa0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
8fb0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
8fc0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
8fd0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
8fe0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
8ff0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
9000: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
9010: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
9020: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
9030: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
9040: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
9050: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
9060: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
9070: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
9080: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
9090: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
90a0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
90b0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
90c0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
90d0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
90e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
90f0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
9100: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
9110: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
9120: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
9130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
9140: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
9150: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
9160: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
9170: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
9180: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
9190: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
91a0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
91b0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
91c0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
91d0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
91e0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
91f0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
9200: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
9210: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
9220: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
9230: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
9240: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
9250: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
9260: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
9270: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
9280: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
9290: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
92a0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
92b0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
92c0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
92d0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
92e0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
92f0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
9300: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
9310: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
9320: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
9330: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
9340: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
9350: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
9360: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
9370: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
9380: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
9390: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
93a0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
93b0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
93c0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
93d0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
93e0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
93f0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
9400: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
9410: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
9420: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
9430: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
9440: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
9450: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
9460: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
9470: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
9480: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
9490: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
94a0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
94b0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
94c0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
94d0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
94e0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
94f0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
9500: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
9510: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
9520: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
9530: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
9540: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
9550: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
9560: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
9570: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
9580: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
9590: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
95a0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
95b0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
95c0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
95d0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
95e0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
95f0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
9600: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
9610: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
9620: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
9630: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
9640: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
9650: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
9660: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
9670: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 all..**.** ^The
9680: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
9690: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 o xAccess() may
96a0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 be [SQLITE_ACCES
96b0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 S_EXISTS].** to
96c0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 test for the exi
96d0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 stence of a file
96e0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
96f0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 ESS_READWRITE] t
9700: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 o.** test whethe
9710: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 r a file is read
9720: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
9730: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
9740: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f CESS_READ].** to
9750: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
9760: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 file is at least
9770: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 readable. The
9780: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a file can be a.*
9790: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a * directory..**.
97a0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
97b0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 always allocate
97c0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e at least mxPathn
97d0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 ame+1 bytes for
97e0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 the.** output bu
97f0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 ffer xFullPathna
9800: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 me. The exact s
9810: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 ize of the outpu
9820: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 t buffer.** is a
9830: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 lso passed as a
9840: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 parameter to bot
9850: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 h methods. If t
9860: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 he output buffer
9870: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 .** is not large
9880: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 enough, [SQLITE
9890: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c _CANTOPEN] shoul
98a0: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 d be returned. S
98b0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 ince this is.**
98c0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 handled as a fat
98d0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 al error by SQLi
98e0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e te, vfs implemen
98f0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 tations should e
9900: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 ndeavor.** to pr
9910: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 event this by se
9920: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 tting mxPathname
9930: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 to a sufficient
9940: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a ly large value..
9950: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f **.** The xRando
9960: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 mness(), xSleep(
9970: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 ), xCurrentTime(
9980: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 ), and xCurrentT
9990: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e imeInt64().** in
99a0: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 terfaces are not
99b0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 strictly a part
99c0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 of the filesyst
99d0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 em, but they are
99e0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 .** included in
99f0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 the VFS structur
9a00: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 e for completene
9a10: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 ss..** The xRand
9a20: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f omness() functio
9a30: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 n attempts to re
9a40: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 turn nBytes byte
9a50: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 s.** of good-qua
9a60: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 lity randomness
9a70: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 into zOut. The
9a80: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a return value is.
9a90: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 ** the actual nu
9aa0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
9ab0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
9ac0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c ined..** The xSl
9ad0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
9ae0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ses the calling
9af0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 thread to sleep
9b00: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 for at.** least
9b10: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
9b20: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e croseconds given
9b30: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 . ^The xCurrent
9b40: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Time().** method
9b50: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 returns a Julia
9b60: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 n Day Number for
9b70: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
9b80: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a e and time as.**
9b90: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
9ba0: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 t value..** ^The
9bb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
9bc0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 64() method retu
9bd0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 rns, as an integ
9be0: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a er, the Julian.*
9bf0: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c * Day Number mul
9c00: 74 69 70 6c 65 64 20 62 79 20 38 36 34 30 30 30 tipled by 864000
9c10: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 00 (the number o
9c20: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 f milliseconds i
9c30: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 n .** a 24-hour
9c40: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 day). .** ^SQLi
9c50: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
9c60: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
9c70: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 4() method to ge
9c80: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a t the current.**
9c90: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 date and time i
9ca0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 f that method is
9cb0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 available (if i
9cc0: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 Version is 2 or
9cd0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 .** greater and
9ce0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 the function poi
9cf0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
9d00: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 ) and will fall
9d10: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 back.** to xCurr
9d20: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 entTime() if xCu
9d30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
9d40: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
9d50: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
9d60: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
9d70: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 qlite3_vfs;.stru
9d80: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
9d90: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
9da0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
9db0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
9dc0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 number (current
9dd0: 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 ly 2) */. int s
9de0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
9df0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
9e00: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
9e10: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
9e20: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
9e30: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
9e40: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
9e50: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
9e60: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
9e70: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
9e80: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
9e90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
9ea0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
9eb0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
9ec0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
9ed0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
9ee0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
9ef0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
9f00: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
9f10: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
9f20: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
9f30: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
9f40: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
9f50: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
9f60: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
9f70: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
9f80: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
9f90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
9fa0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
9fb0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
9fc0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
9fd0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
9fe0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
9ff0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
a000: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
a010: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
a020: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
a030: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
a040: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
a050: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
a060: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
a070: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
a080: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
a090: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
a0a0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
a0b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
a0c0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
a0d0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
a0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
a0f0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
a100: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
a110: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
a120: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
a130: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
a140: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
a150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
a160: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
a170: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
a180: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
a190: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
a1a0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
a1b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
a1c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
a1d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
a1e0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
a1f0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
a200: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 char *);. /*.
a210: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
a220: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
a230: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c ion 1 of the sql
a240: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 ite_vfs object.
a250: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 ** definition.
a260: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c Those that foll
a270: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 ow are added in
a280: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 version 2 or lat
a290: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a er. */. int (*
a2a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
a2b0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 4)(sqlite3_vfs*,
a2c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 sqlite3_int64*)
a2d0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
a2e0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
a2f0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 e in versions 1
a300: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c and 2 of the sql
a310: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
a320: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
a330: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
a340: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
a350: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
a360: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
a370: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
a380: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
a390: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
a3a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
a3b0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
a3c0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
a3d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
a3e0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
a3f0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
a400: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
a410: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
a420: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
a430: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
a440: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
a450: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
a460: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
a470: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
a480: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
a490: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
a4a0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
a4b0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
a4c0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
a4d0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
a4e0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
a4f0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
a500: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
a510: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
a520: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
a530: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
a540: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
a550: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
a560: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
a570: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
a580: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
a590: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
a5a0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
a5b0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
a5c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
a5d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
a5e0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
a5f0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
a600: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
a610: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
a620: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
a630: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
a640: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
a650: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
a660: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
a670: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
a680: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
a690: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
a6a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
a6b0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
a6c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
a6d0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
a6e0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
a6f0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
a700: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
a710: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
a720: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
a730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
a740: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
a750: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
a760: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
a770: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
a780: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
a790: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
a7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
a7b0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
a7c0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
a7d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
a7e0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
a7f0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
a800: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
a810: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
a820: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
a830: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
a840: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
a850: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
a860: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
a870: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
a880: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
a890: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
a8a0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
a8b0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
a8c0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
a8d0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
a8e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
a8f0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
a900: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
a910: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
a920: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
a930: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
a940: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
a950: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
a960: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
a970: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
a980: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
a990: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
a9a0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
a9b0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
a9c0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
a9d0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
a9e0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
a9f0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
aa00: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 ven no the corre
aa10: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
aa20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
aa30: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
aa40: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
aa50: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
aa60: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
aa70: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
aa80: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
aa90: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
aaa0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
aab0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
aac0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
aad0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
aae0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
aaf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
ab00: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
ab10: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
ab20: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
ab30: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
ab40: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
ab50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
ab60: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
ab70: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
ab80: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
ab90: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
aba0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
abb0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
abc0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
abd0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
abe0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
abf0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
ac00: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
ac10: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
ac20: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
ac30: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
ac40: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
ac50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
ac60: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
ac70: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
ac80: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
ac90: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
aca0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
acb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
acc0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
acd0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
ace0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
acf0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
ad00: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
ad10: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
ad20: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
ad30: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
ad40: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
ad50: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
ad60: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
ad70: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
ad80: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
ad90: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
ada0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
adb0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
adc0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
add0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
ade0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
adf0: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
ae00: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
ae10: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
ae20: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
ae30: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
ae40: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
ae50: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
ae60: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
ae70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
ae80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
ae90: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
aea0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
aeb0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
aec0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
aed0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
aee0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
aef0: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
af00: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
af10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
af20: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
af30: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
af40: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
af50: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
af60: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
af70: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
af80: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
af90: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
afa0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
afb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
afc0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
afd0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
afe0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
aff0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
b000: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
b010: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
b020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
b030: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
b040: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
b050: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
b060: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
b070: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
b080: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
b090: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
b0a0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
b0b0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
b0c0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
b0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
b0e0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
b0f0: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
b100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
b110: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
b120: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
b130: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
b140: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
b150: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
b160: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
b170: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
b180: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
b190: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
b1a0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
b1b0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
b1c0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
b1d0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
b1e0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
b1f0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
b200: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
b210: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
b220: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
b230: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
b240: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
b250: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
b260: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
b270: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
b280: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
b290: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
b2a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
b2b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
b2c0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
b2d0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
b2e0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
b2f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
b300: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
b310: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
b320: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
b330: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
b340: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
b350: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
b360: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
b370: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
b380: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
b390: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
b3a0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
b3b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
b3c0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
b3d0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
b3e0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
b3f0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
b400: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
b410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
b420: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
b430: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
b440: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
b450: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
b460: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
b470: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
b480: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
b490: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
b4a0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
b4b0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
b4c0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
b4d0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
b4e0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
b4f0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
b500: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
b510: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
b520: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
b530: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
b540: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
b550: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
b560: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
b570: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
b580: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
b590: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
b5a0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
b5b0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
b5c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
b5d0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
b5e0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
b5f0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
b600: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
b610: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
b620: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
b630: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
b640: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
b650: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
b660: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
b670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
b680: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
b690: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
b6a0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
b6b0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
b6c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
b6d0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
b6e0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
b6f0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
b700: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
b710: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
b720: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
b730: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
b740: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
b750: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
b760: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
b770: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
b780: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
b790: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
b7a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
b7b0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
b7c0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
b7d0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
b7e0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
b7f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
b800: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
b810: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
b820: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
b830: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
b840: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
b850: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
b860: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
b870: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
b880: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
b890: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
b8a0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
b8b0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
b8c0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
b8d0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
b8e0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
b8f0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
b900: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
b910: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
b920: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
b930: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
b940: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
b950: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
b960: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
b970: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
b980: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
b990: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
b9a0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
b9b0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
b9c0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
b9d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
b9e0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
b9f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
ba00: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
ba10: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
ba20: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
ba30: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
ba40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ba50: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
ba60: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
ba70: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
ba80: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
ba90: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
baa0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
bab0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
bac0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
bad0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
bae0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
baf0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
bb00: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
bb10: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
bb20: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
bb30: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
bb40: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
bb50: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
bb60: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
bb70: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
bb80: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
bb90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
bba0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
bbb0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
bbc0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
bbd0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
bbe0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
bbf0: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
bc00: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
bc10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
bc20: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
bc30: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
bc40: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
bc50: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
bc60: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
bc70: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
bc80: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
bc90: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 failure..*/.int
bca0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
bcb0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 ze(void);.int sq
bcc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
bcd0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
bce0: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 3_os_init(void);
bcf0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f .int sqlite3_os_
bd00: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
bd10: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
bd20: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
bd30: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
bd40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
bd50: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
bd60: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
bd70: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
bd80: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
bd90: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
bda0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
bdb0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
bdc0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
bdd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
bde0: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
bdf0: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
be00: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
be10: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
be20: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
be30: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
be40: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
be50: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
be60: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
be70: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
be80: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
be90: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
bea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
beb0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
bec0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
bed0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
bee0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
bef0: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
bf00: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
bf10: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
bf20: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
bf30: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
bf40: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
bf50: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
bf60: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
bf70: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
bf80: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
bf90: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
bfa0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
bfb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
bfc0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
bfd0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
bfe0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
bff0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 ** ^If sqlite3_c
c000: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 onfig() is calle
c010: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
c020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 _initialize()] a
c030: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 nd before.** [sq
c040: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
c050: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 ] then it will r
c060: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
c070: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f USE..** Note, ho
c080: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c wever, that ^sql
c090: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 ite3_config() ca
c0a0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 n be called as p
c0b0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d art of the.** im
c0c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
c0d0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
c0e0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f efined [sqlite3_
c0f0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a os_init()]..**.*
c100: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
c110: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
c120: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 config() is an i
c130: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 nteger.** [SQLIT
c140: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
c150: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 HREAD | configur
c160: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 ation option] th
c170: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a at determines.**
c180: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f what property o
c190: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 f SQLite is to b
c1a0: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 e configured. S
c1b0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
c1c0: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 nts.** vary depe
c1d0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 nding on the [SQ
c1e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
c1f0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
c200: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
c210: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
c220: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
c230: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 ^When a configu
c240: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
c250: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f set, sqlite3_co
c260: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b nfig() returns [
c270: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e SQLITE_OK]..** ^
c280: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
c290: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
c2a0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
c2b0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
c2c0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
c2d0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
c2e0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
c2f0: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 de]..*/.int sqli
c300: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 te3_config(int,
c310: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
c320: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 I3REF: Configure
c330: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
c340: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tions.**.** The
c350: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
c360: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
c370: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f used to make co
c380: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
c390: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 hanges to a [dat
c3a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c3b0: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 ]. The interfac
c3c0: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a e is similar to.
c3d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
c3e0: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 ig()] except tha
c3f0: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 t the changes ap
c400: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a ply to a single.
c410: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
c420: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 nection] (specif
c430: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 ied in the first
c440: 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 argument). The
c450: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 .** sqlite3_db_c
c460: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
c470: 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 e should only be
c480: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c used immediatel
c490: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 y after.** the d
c4a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
c4b0: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 on is created us
c4c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 ing [sqlite3_ope
c4d0: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 n()],.** [sqlite
c4e0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 3_open16()], or
c4f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
c500: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ()]. .**.** The
c510: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
c520: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
c530: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
c540: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 is the.** config
c550: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 uration verb - a
c560: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
c570: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
c580: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 at.** aspect of
c590: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
c5a0: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 nnection] is bei
c5b0: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a ng configured..*
c5c0: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 * The only choic
c5d0: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 e for this value
c5e0: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f is [SQLITE_DBCO
c5f0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e NFIG_LOOKASIDE].
c600: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 .** New verbs ar
c610: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 e likely to be a
c620: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
c630: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
c640: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c e..** Additional
c650: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e arguments depen
c660: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a d on the verb..*
c670: 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 *.** ^Calls to s
c680: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
c690: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 () return SQLITE
c6a0: 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 _OK if and only
c6b0: 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 if.** the call i
c6c0: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 s considered suc
c6d0: 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 cessful..*/.int
c6e0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
c6f0: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 g(sqlite3*, int
c700: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a op, ...);../*.**
c710: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
c720: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 y Allocation Rou
c730: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 tines.**.** An i
c740: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
c750: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
c760: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
c770: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ween SQLite.** a
c780: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d nd low-level mem
c790: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
c7a0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
c7b0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 his object is us
c7c0: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 ed in only one p
c7d0: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 lace in the SQLi
c7e0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
c7f0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e A pointer to an
c800: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
c810: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 s object is the
c820: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b argument to.** [
c830: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
c840: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 ] when the confi
c850: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
c860: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f is.** [SQLITE_CO
c870: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 NFIG_MALLOC] or
c880: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
c890: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 ETMALLOC]. .**
c8a0: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 By creating an i
c8b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
c8c0: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 object.** and pa
c8d0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
c8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
c8f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
c900: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 OC]).** during c
c910: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e onfiguration, an
c920: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
c930: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 specify an alte
c940: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 rnative.** memor
c950: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
c960: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 system for SQLit
c970: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c e to use for all
c980: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d of its.** dynam
c990: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e ic memory needs.
c9a0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
c9b0: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 SQLite comes wi
c9c0: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c th several [buil
c9d0: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
c9e0: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 cators].** that
c9f0: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 are perfectly ad
ca00: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f equate for the o
ca10: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f verwhelming majo
ca20: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
ca30: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 ions.** and that
ca40: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
ca50: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 only useful to a
ca60: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f tiny minority o
ca70: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
ca80: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a * with specializ
ca90: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
caa0: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 tion requirement
cab0: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 s. This object
cac0: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 is.** also used
cad0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f during testing o
cae0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 f SQLite in orde
caf0: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 r to specify an
cb00: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
cb10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
cb20: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d that simulates m
cb30: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d emory out-of-mem
cb40: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 ory conditions i
cb50: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 n.** order to ve
cb60: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 rify that SQLite
cb70: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 recovers gracef
cb80: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a ully from such.*
cb90: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a * conditions..**
cba0: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 .** The xMalloc
cbb0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
cbc0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
cbd0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
cbe0: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
cbf0: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
cc00: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
cc10: 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c y..** The xReall
cc20: 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 oc method must w
cc30: 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 ork like realloc
cc40: 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e () from the stan
cc50: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a dard C library.*
cc60: 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 * with the excep
cc70: 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 tion that if the
cc80: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
cc90: 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 to xRealloc is
cca0: 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f zero,.** xReallo
ccb0: 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f c must be a no-o
ccc0: 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 p - it must not
ccd0: 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f perform any allo
cce0: 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 cation or.** dea
ccf0: 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c llocation. ^SQL
cd00: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 ite guarantees t
cd10: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 hat the second a
cd20: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 rgument to.** xR
cd30: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 ealloc is always
cd40: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 a value returne
cd50: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c d by a prior cal
cd60: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a l to xRoundup..*
cd70: 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 * And so in case
cd80: 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 s where xRoundup
cd90: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
cda0: 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 a positive numbe
cdb0: 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 r,.** xRealloc c
cdc0: 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 an perform exact
cdd0: 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 ly as the standa
cde0: 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c rd library reall
cdf0: 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c oc() and.** stil
ce00: 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e l be in complian
ce10: 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 ce with this spe
ce20: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a cification..**.*
ce30: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
ce40: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
ce50: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
ce60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
ce70: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
ce80: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
ce90: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
cea0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
ceb0: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
cec0: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
ced0: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
cee0: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
cef0: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
cf00: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
cf10: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
cf20: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
cf30: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
cf40: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
cf50: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
cf60: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
cf70: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
cf80: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
cf90: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
cfa0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
cfb0: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
cfc0: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
cfd0: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
cfe0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
cff0: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
d000: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
d010: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 power of 2..** E
d020: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
d030: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 cation request c
d040: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 oming in through
d050: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
d060: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
d070: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 e3_realloc()] fi
d080: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 rst calls xRound
d090: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 up. If xRoundup
d0a0: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 returns 0, .**
d0b0: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 that causes the
d0c0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 corresponding me
d0d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
d0e0: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 to fail..**.** T
d0f0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
d100: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
d110: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
d120: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c . (For example,
d130: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
d140: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
d150: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
d160: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
d170: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
d180: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
d190: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
d1a0: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
d1b0: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
d1c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
d1d0: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
d1e0: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
d1f0: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
d200: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
d210: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
d220: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
d230: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
d240: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
d250: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c tdown..**.** SQL
d260: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 ite holds the [S
d270: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
d280: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 IC_MASTER] mutex
d290: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 when it invokes
d2a0: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 .** the xInit me
d2b0: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e thod, so the xIn
d2c0: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e it method need n
d2d0: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 ot be threadsafe
d2e0: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 . The.** xShutd
d2f0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e own method is on
d300: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b ly called from [
d310: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
d320: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a ()] so it does.*
d330: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 * not need to be
d340: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 threadsafe eith
d350: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 er. For all oth
d360: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 er methods, SQLi
d370: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 te.** holds the
d380: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
d390: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 ATIC_MEM] mutex
d3a0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a as long as the.*
d3b0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
d3c0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 _MEMSTATUS] conf
d3d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
d3e0: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 is turned on (w
d3f0: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 hich.** it is by
d400: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f default) and so
d410: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 the methods are
d420: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 automatically s
d430: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f erialized..** Ho
d440: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 wever, if [SQLIT
d450: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
d460: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c US] is disabled,
d470: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a then the other.
d480: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ** methods must
d490: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 be threadsafe or
d4a0: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 else make their
d4b0: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 own arrangement
d4c0: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 s for.** seriali
d4d0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 zation..**.** SQ
d4e0: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
d4f0: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d invoke xInit() m
d500: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 ore than once wi
d510: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 thout an interve
d520: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 ning.** call to
d530: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a xShutdown()..*/.
d540: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
d550: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d560: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
d570: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
d580: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
d590: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
d5a0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
d5b0: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
d5c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
d5d0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
d5e0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
d5f0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
d600: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
d610: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
d620: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
d630: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
d640: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
d650: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
d660: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
d670: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
d680: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
d690: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
d6a0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
d6b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
d6c0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
d6d0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
d6e0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
d6f0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
d700: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
d710: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
d720: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
d730: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
d740: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
d750: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
d760: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
d770: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
d780: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
d790: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
d7a0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
d7b0: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
d7c0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
d7d0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
d7e0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
d7f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
d800: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
d810: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
d820: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d830: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
d840: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
d850: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
d860: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
d870: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
d880: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
d890: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
d8a0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
d8b0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
d8c0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
d8d0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
d8e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
d8f0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
d900: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
d910: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
d920: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
d930: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
d940: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
d950: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
d960: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
d970: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
d980: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
d990: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
d9a0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
d9b0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
d9c0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
d9d0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
d9e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
d9f0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
da00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
da10: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
da20: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
da30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
da40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
da50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
da60: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
da70: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
da80: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
da90: 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
daa0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
dab0: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
dac0: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
dad0: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
dae0: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
daf0: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
db00: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
db10: 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
db20: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
db30: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
db40: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
db50: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
db60: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
db70: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
db80: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
db90: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
dba0: 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
dbb0: 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
dbc0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
dbd0: 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
dbe0: 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
dbf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
dc00: 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
dc10: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
dc20: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
dc30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
dc40: 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
dc50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
dc60: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
dc70: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
dc80: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
dc90: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
dca0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
dcb0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
dcc0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
dcd0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
dce0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c ing mode] to Mul
dcf0: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f ti-thread. In o
dd00: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
dd10: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
dd20: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
dd30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
dd40: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
dd50: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
dd60: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
dd70: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
dd80: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
dd90: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
dda0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ddb0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
ddc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
ddd0: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
dde0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
ddf0: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
de00: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
de10: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
de20: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
de30: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
de40: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
de50: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
de60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
de70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
de80: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
de90: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 ime. ^If SQLite
dea0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
deb0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
dec0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
ded0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
dee0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
def0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
df00: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
df10: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c e to set the Mul
df20: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
df30: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
df40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
df50: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
df60: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
df70: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
df80: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
df90: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
dfa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
dfb0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
dfc0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
dfd0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 IG_SERIALIZED</d
dfe0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
dff0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
e000: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
e010: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
e020: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
e030: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
e040: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 erialized. In ot
e050: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 her words, this
e060: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
e070: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
e080: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
e090: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
e0a0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
e0b0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
e0c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
e0d0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
e0e0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
e0f0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
e100: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
e110: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
e120: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
e130: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
e140: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
e150: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
e160: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
e170: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e180: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
e190: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
e1a0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
e1b0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
e1c0: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
e1d0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
e1e0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
e1f0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
e200: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
e210: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
e220: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
e230: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 me..** ^If SQLit
e240: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
e250: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
e260: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
e270: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
e280: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
e290: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
e2a0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
e2b0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 le to set the Se
e2c0: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
e2d0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
e2e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
e2f0: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
e300: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
e310: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
e320: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
e330: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f IG_SERIALIZED co
e340: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e350: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
e360: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
e370: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
e380: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
e390: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
e3a0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
e3b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
e3c0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
e3d0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
e3e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
e3f0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
e400: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
e410: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
e420: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
e430: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
e440: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
e450: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 n place of.** th
e460: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
e470: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 ion routines bui
e480: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
e490: 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a ^ ^SQLite makes.
e4a0: 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ** its own priva
e4b0: 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 te copy of the c
e4c0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
e4d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
e4e0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ds] structure.**
e4f0: 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c before the [sql
e500: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 ite3_config()] c
e510: 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 all returns.</dd
e520: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
e530: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
e540: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
e550: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
e560: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
e570: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
e580: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
e590: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
e5a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
e5b0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
e5c0: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 re. The [sqlite
e5d0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
e5e0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
e5f0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
e600: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
e610: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
e620: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
e630: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
e640: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
e650: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
e660: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
e670: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
e680: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
e690: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
e6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
e6b0: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
e6c0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
e6d0: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
e6e0: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
e6f0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
e700: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
e710: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
e720: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
e730: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
e740: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 e int, interpret
e750: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c ed as a .** bool
e760: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
e770: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
e780: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
e790: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
e7a0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 on .** statistic
e7b0: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
e7c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
e7d0: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
e7e0: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c led, the .** fol
e7f0: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
e800: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
e810: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
e820: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
e830: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
e840: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
e850: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
e860: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
e870: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
e880: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
e890: 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
e8a0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
e8b0: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f tatus()].** </
e8c0: 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
e8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
e8e0: 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
e8f0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
e900: 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
e910: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
e920: 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
e930: 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
e940: 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
e950: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
e960: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
e970: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
e980: 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
e990: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
e9a0: 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 NFIG_SCRATCH</dt
e9b0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
e9c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
e9d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
e9e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
e9f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a ite can use for.
ea00: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
ea10: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 y. There are th
ea20: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 ree arguments:
ea30: 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 A pointer an 8-b
ea40: 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d yte.** aligned m
ea50: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f emory buffer fro
ea60: 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 m which the scra
ea70: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
ea80: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
ea90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
eaa0: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
eab0: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
eac0: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
ead0: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
eae0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
eaf0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
eb00: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
eb10: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a ultiple of 16..*
eb20: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
eb30: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
eb40: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
eb50: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
eb60: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
eb70: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
eb80: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
eb90: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d te will use no m
eba0: 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 ore than two scr
ebb0: 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
ebc0: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
ebd0: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
ebe0: 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 to twice the exp
ebf0: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 ected maximum nu
ec00: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e mber of threads.
ec10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
ec20: 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 never require a
ec30: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
ec40: 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 that is more tha
ec50: 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 n 6.** times the
ec60: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
ec70: 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ize. ^If SQLite
ec80: 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
ec90: 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
eca0: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
ecb0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
ecc0: 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
ecd0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
ece0: 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
ecf0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
ed00: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
ed10: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
ed20: 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ded.</dd>.**.**
ed30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
ed40: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e G_PAGECACHE</dt>
ed50: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
ed60: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
ed70: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
ed80: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
ed90: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
eda0: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 * the database p
edb0: 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 age cache with t
edc0: 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 he default page
edd0: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 cache implemenat
ede0: 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 ion. .** This c
edf0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f onfiguration sho
ee00: 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
ee10: 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
ee20: 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a n-define page.**
ee30: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
ee40: 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 ation is loaded
ee50: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 using the SQLITE
ee60: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f _CONFIG_PCACHE o
ee70: 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
ee80: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
ee90: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
eea0: 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
eeb0: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
eec0: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
eed0: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
eee0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
eef0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
ef00: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
ef10: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
ef20: 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
ef30: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
ef40: 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
ef50: 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
ef60: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
ef70: 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
ef80: 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
ef90: 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
efa0: 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
efb0: 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
efc0: 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
efd0: 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
efe0: 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
eff0: 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
f000: 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
f010: 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
f020: 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
f030: 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
f040: 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
f050: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
f060: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
f070: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
f080: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
f090: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
f0a0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
f0b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
f0c0: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
f0d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
f0e0: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
f0f0: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
f100: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
f110: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
f120: 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
f130: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
f140: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
f150: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
f160: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
f170: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
f180: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
f190: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
f1a0: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
f1b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
f1c0: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
f1d0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
f1e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
f1f0: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
f200: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
f210: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
f220: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
f230: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
f240: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
f250: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
f260: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
f270: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
f280: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
f290: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
f2a0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
f2b0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
f2c0: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 e.** for all of
f2d0: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
f2e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
f2f0: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 eds beyond those
f300: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
f310: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
f320: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
f330: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
f340: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
f350: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
f360: 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 guments: An 8-by
f370: 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
f380: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
f390: 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
f3a0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
f3b0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
f3c0: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
f3d0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
f3e0: 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
f3f0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
f400: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
f410: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
f420: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
f430: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
f440: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
f450: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
f460: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
f470: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
f480: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
f490: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
f4a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
f4b0: 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
f4c0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
f4d0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
f4e0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
f4f0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
f500: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
f510: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
f520: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
f530: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
f540: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
f550: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
f560: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
f570: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
f580: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
f590: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
f5a0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
f5b0: 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
f5c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
f5d0: 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
f5e0: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
f5f0: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
f600: 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
f610: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a fined.</dd>.**.*
f620: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
f630: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a FIG_MUTEX</dt>.*
f640: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
f650: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
f660: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
f670: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
f680: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
f690: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
f6a0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
f6b0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
f6c0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
f6d0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
f6e0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 ve low-level mut
f6f0: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 ex routines to b
f700: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a e used in place.
f710: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 ** the mutex rou
f720: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
f730: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c SQLite.)^ ^SQL
f740: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
f750: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 of the.** conte
f760: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 nt of the [sqlit
f770: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
f780: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f ] structure befo
f790: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a re the call to.*
f7a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
f7b0: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 g()] returns. ^I
f7c0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
f7d0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
f7e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
f7f0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
f800: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
f810: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
f820: 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
f830: 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
f840: 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
f850: 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
f860: 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
f870: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
f880: 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
f890: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
f8a0: 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
f8b0: 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
f8c0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
f8d0: 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
f8e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
f8f0: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f ONFIG_GETMUTEX</
f900: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
f910: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
f920: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
f930: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
f940: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
f950: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
f960: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
f970: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
f980: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
f990: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
f9a0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
f9b0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
f9c0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
f9d0: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
f9e0: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
f9f0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
fa00: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
fa10: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
fa20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
fa30: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
fa40: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
fa50: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
fa60: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
fa70: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
fa80: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
fa90: 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 le. ^If SQLite
faa0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
fab0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
fac0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
fad0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
fae0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
faf0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
fb00: 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
fb10: 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
fb20: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
fb30: 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
fb40: 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
fb50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
fb60: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
fb70: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
fb80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
fb90: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
fba0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
fbb0: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c R].</dd>.**.** <
fbc0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
fbd0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
fbe0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
fbf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
fc00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
fc10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 etermine the def
fc20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 ault.** memory a
fc30: 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 llocation for th
fc40: 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
fc50: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 ry allocator on
fc60: 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
fc70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
fc80: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
fc90: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
fca0: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
fcb0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
fcc0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
fcd0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
fce0: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
fcf0: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
fd00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 ase connection.)
fd10: 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e ^ ^(This option
fd20: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e sets the.** <i>
fd30: 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b default</i> look
fd40: 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 aside size. The
fd50: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
fd60: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 _LOOKASIDE].** v
fd70: 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f erb to [sqlite3_
fd80: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e db_config()] can
fd90: 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e be used to chan
fda0: 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
fdb0: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
fdc0: 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
fdd0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c connections.)^ <
fde0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
fdf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
fe00: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
fe10: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
fe20: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
fe30: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
fe40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
fe50: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
fe60: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 he_methods] obje
fe70: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ct. This object
fe80: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 specifies the i
fe90: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 nterface.** to a
fea0: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
feb0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
fec0: 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 n.)^ ^SQLite ma
fed0: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
fee0: 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 e.** object and
fef0: 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 uses it for page
ff00: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c cache memory al
ff10: 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a locations.</dd>.
ff20: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
ff30: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
ff40: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
ff50: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
ff60: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
ff70: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
ff80: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
ff90: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
ffa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
ffb0: 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
ffc0: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
ffd0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
ffe0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
fff0: 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
10000 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
10010 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
10020 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OG</dt>.** <dd>
10030 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
10040 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
10050 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
10060 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
10070 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
10080 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
10090 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
100a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
100b0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
100c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
100d0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
100e0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
100f0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
10100 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
10110 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
10120 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
10130 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
10140 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
10150 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
10160 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
10170 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
10180 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
10190 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
101a0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
101b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
101c0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
101d0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
101e0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
101f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
10200 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
10210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
10220 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
10230 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
10240 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
10250 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
10260 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
10270 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
10280 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
10290 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
102a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
102b0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
102c0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
102d0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
102e0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
102f0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
10300 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
10310 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
10320 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
10330 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
10340 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
10350 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
10360 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
10370 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
10380 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
10390 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
103a0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
103b0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
103c0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
103d0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
103e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
103f0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
10400 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
10410 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
10420 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
10430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
10440 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
10450 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
10460 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
10470 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
10480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
10490 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
104a0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 THREAD 1 /* ni
104b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
104c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
104d0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e THREAD 2 /* n
104e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
104f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
10500 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 ALIZED 3 /*
10510 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
10520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
10530 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a LOC 4 /*
10540 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
10550 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
10560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
10570 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 ETMALLOC 5
10580 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
10590 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
105a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
105b0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 _SCRATCH 6
105c0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
105d0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
105e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
105f0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
10600 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
10610 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
10620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
10630 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
10640 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
10650 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
10660 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
10670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
10680 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
10690 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
106a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
106b0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
106c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
106d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
106e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
106f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
10700 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
10710 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
10720 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 */./* previously
10730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
10740 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 HUNKALLOC 12 whi
10750 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 ch is now unused
10760 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 . */ .#define SQ
10770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
10780 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 ASIDE 13 /*
10790 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
107a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
107b0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 _PCACHE 14
107c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
107d0 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a che_methods* */.
107e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
107f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 ONFIG_GETPCACHE
10800 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 15 /* sqlite
10810 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
10820 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
10830 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 ITE_CONFIG_LOG
10840 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 16 /* x
10850 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a Func, void* */..
10860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
10870 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
10880 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
10890 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
108a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
108b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
108c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
108d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
108e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
108f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
10900 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
10910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
10920 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
10930 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
10940 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10950 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
10960 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
10970 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
10980 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
10990 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
109a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
109b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
109c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
109d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
109e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
109f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
10a00 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
10a10 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
10a20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
10a30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
10a40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
10a50 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
10a60 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
10a70 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
10a80 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
10a90 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
10aa0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
10ab0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
10ac0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
10ad0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
10ae0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
10af0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
10b00 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
10b10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
10b20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
10b30 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
10b40 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
10b50 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
10b60 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
10b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
10b80 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
10b90 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
10ba0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
10bb0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
10bc0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
10bd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d ointer to an mem
10be0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
10bf0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
10c00 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
10c10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
10c20 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
10c30 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
10c40 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
10c50 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
10c60 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
10c70 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
10c80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
10c90 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
10ca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
10cb0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
10cc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
10cd0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
10ce0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
10cf0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
10d00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
10d10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
10d20 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
10d30 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
10d40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
10d50 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
10d60 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
10d70 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
10d80 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
10d90 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
10da0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
10db0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
10dc0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
10dd0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
10de0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
10df0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
10e00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
10e10 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
10e20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
10e30 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
10e40 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
10e50 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
10e60 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
10e70 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
10e80 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
10e90 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
10ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
10eb0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
10ec0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
10ed0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
10ee0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
10ef0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
10f00 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
10f10 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
10f20 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
10f30 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
10f40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
10f50 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
10f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
10f70 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
10f80 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
10f90 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
10fa0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
10fb0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
10fc0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
10fd0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
10fe0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
10ff0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
11000 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
11010 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
11020 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
11030 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
11040 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
11050 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
11060 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 1001 /* void*
11070 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a int int */.../*.
11080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
11090 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
110a0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
110b0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 odes.**.** ^The
110c0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
110d0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
110e0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
110f0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
11100 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
11110 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
11120 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
11130 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
11140 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
11150 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
11160 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
11170 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
11180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
11190 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
111a0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
111b0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
111c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
111d0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
111e0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
111f0 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
11200 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
11210 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
11220 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
11230 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
11240 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 | "rowid"]. ^Th
11250 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
11260 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
11270 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
11280 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
11290 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
112a0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
112b0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
112c0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
112d0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
112e0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
112f0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 ^If.** the table
11300 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
11310 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
11320 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
11330 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
11340 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
11350 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
11360 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
11370 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
11380 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d [rowid] of the m
11390 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 ost recent.** su
113a0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
113b0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 ] into the datab
113c0 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 ase from the [da
113d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
113e0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
113f0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 st argument. ^I
11400 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 f no successful
11410 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 [INSERT]s.** hav
11420 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 e ever occurred
11430 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 on that database
11440 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 connection, zer
11450 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a o is returned..*
11460 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e *.** ^(If an [IN
11470 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 SERT] occurs wit
11480 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 hin a trigger, t
11490 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 hen the [rowid]
114a0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a of the inserted.
114b0 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e ** row is return
114c0 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
114d0 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ne as long as th
114e0 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e e trigger is run
114f0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 ning..** But onc
11500 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 e the trigger te
11510 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 rminates, the va
11520 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
11530 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
11540 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c reverts to the l
11550 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 ast value insert
11560 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 ed before the tr
11570 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a igger fired.)^.*
11580 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 *.** ^An [INSERT
11590 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 ] that fails due
115a0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 to a constraint
115b0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f violation is no
115c0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 t a.** successfu
115d0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 l [INSERT] and d
115e0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
115f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
11600 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 d by this.** rou
11610 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 tine. ^Thus INS
11620 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 ERT OR FAIL, INS
11630 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 ERT OR IGNORE, I
11640 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 NSERT OR ROLLBAC
11650 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 K,.** and INSERT
11660 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e OR ABORT make n
11670 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 o changes to the
11680 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
11690 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
116a0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 when their inse
116b0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 rtion fails. ^(
116c0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
116d0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
116e0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
116f0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
11700 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
11710 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
11720 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
11730 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
11740 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
11750 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
11760 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
11770 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
11780 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
11790 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
117a0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
117b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e his interface.)^
117c0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 .**.** ^For the
117d0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 purposes of this
117e0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e routine, an [IN
117f0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 SERT] is conside
11800 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 red to.** be suc
11810 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 cessful even if
11820 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 it is subsequent
11830 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
11840 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
11850 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c ion is accessibl
11860 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 e to SQL stateme
11870 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b nts via the.** [
11880 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
11890 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e d() SQL function
118a0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
118b0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 parate thread pe
118c0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e rforms a new [IN
118d0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d SERT] on the sam
118e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
118f0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 nnection while t
11900 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
11910 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
11920 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
11930 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 running and thus
11940 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 changes the las
11950 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
11960 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 ,.** then the va
11970 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
11980 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
11990 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
119a0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c .** unpredictabl
119b0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 e and might not
119c0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 equal either the
119d0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a old or the new.
119e0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b ** last insert [
119f0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 rowid]..*/.sqlit
11a00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
11a10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
11a20 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
11a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
11a40 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 ount The Number
11a50 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
11a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
11a70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
11a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 e number of data
11a90 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 base rows that w
11aa0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f ere changed.** o
11ab0 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 r inserted or de
11ac0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 leted by the mos
11ad0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
11ae0 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 eted SQL stateme
11af0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 nt.** on the [da
11b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11b10 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 n] specified by
11b20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
11b30 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 ter..** ^(Only c
11b40 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 hanges that are
11b50 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 directly specifi
11b60 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 ed by the [INSER
11b70 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a T], [UPDATE],.**
11b80 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
11b90 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 tement are count
11ba0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 ed. Auxiliary c
11bb0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
11bc0 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 .** triggers or
11bd0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
11be0 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f ions] are not co
11bf0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 unted.)^ Use the
11c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 .** [sqlite3_tot
11c10 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 al_changes()] fu
11c20 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 nction to find t
11c30 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
11c40 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e of changes.** in
11c50 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 cluding changes
11c60 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 caused by trigge
11c70 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b rs and foreign k
11c80 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a ey actions..**.*
11c90 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 * ^Changes to a
11ca0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 view that are si
11cb0 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 mulated by an [I
11cc0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
11cd0 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f r].** are not co
11ce0 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 unted. Only rea
11cf0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 l table changes
11d00 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a are counted..**.
11d10 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e ** ^(A "row chan
11d20 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 ge" is a change
11d30 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 to a single row
11d40 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c of a single tabl
11d50 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 e.** caused by a
11d60 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 n INSERT, DELETE
11d70 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 , or UPDATE stat
11d80 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 ement. Rows tha
11d90 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 t.** are changed
11da0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 as side effects
11db0 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f of [REPLACE] co
11dc0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
11dd0 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b ion,.** rollback
11de0 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 , ABORT processi
11df0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d ng, [DROP TABLE]
11e00 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 , or by any othe
11e10 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 r.** mechanisms
11e20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
11e30 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
11e40 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 es.)^.**.** A "t
11e50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 rigger context"
11e60 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 is a scope of ex
11e70 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 ecution that beg
11e80 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 ins and.** ends
11e90 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 with the script
11ea0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 of a [CREATE TRI
11eb0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e GGER | trigger].
11ec0 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 .** Most SQL st
11ed0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 atements are.**
11ee0 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 evaluated outsid
11ef0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 e of any trigger
11f00 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 . This is the "
11f10 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 top level".** tr
11f20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 igger context.
11f30 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 If a trigger fir
11f40 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 es from the top
11f50 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 level, a.** new
11f60 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 trigger context
11f70 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 is entered for t
11f80 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 he duration of t
11f90 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 hat one.** trigg
11fa0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 er. Subtriggers
11fb0 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 create subconte
11fc0 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 xts for their du
11fd0 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ration..**.** ^C
11fe0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
11ff0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 exec()] or [sqli
12000 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 te3_step()] recu
12010 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 rsively does.**
12020 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 not create a new
12030 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
12040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 ..**.** ^This fu
12050 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
12060 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 he number of dir
12070 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 ect row changes
12080 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 in the.** most r
12090 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
120a0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 DATE, or DELETE
120b0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
120c0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 the same.** tri
120d0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
120e0 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 .** ^Thus, when
120f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
12100 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 top level, this
12110 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
12120 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
12130 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 f changes in the
12140 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
12150 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
12160 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 DELETE.** that a
12170 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 lso occurred at
12180 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 the top level.
12190 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 ^(Within the bod
121a0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a y of a trigger,.
121b0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ** the sqlite3_c
121c0 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 hanges() interfa
121d0 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ce can be called
121e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
121f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 ber of.** change
12200 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 s in the most re
12210 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
12220 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
12230 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 or DELETE.** st
12240 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
12250 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 he body of the s
12260 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 ame trigger..**
12270 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d However, the num
12280 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 ber returned doe
12290 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
122a0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 anges.** caused
122b0 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 by subtriggers s
122c0 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 ince those have
122d0 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 their own contex
122e0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 t.)^.**.** See a
122f0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
12300 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
12310 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
12320 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
12330 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
12340 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
12350 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
12360 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
12370 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
12380 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
12390 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
123a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
123b0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
123c0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
123d0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
123e0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
123f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
12400 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
12410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 /.int sqlite3_ch
12420 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
12430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12440 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f : Total Number O
12450 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
12460 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
12470 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
12480 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 number of row c
12490 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
124a0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 [INSERT],.** [U
124b0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
124c0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 E] statements si
124d0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 nce the [databas
124e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 e connection] wa
124f0 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 s opened..** ^(T
12500 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 he count returne
12510 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 d by sqlite3_tot
12520 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 al_changes() inc
12530 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 ludes all change
12540 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 s.** from all [C
12550 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
12560 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 trigger] context
12570 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 s and changes ma
12580 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 de by.** [foreig
12590 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 n key actions].
125a0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 However,.** the
125b0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
125c0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 nclude changes u
125d0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
125e0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
125f0 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f raints,.** do ro
12600 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 llbacks or ABORT
12610 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 processing, or
12620 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f [DROP TABLE] pro
12630 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a cessing. The.**
12640 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
12650 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 include rows of
12660 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 views that fire
12670 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 an [INSTEAD OF t
12680 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 rigger],.** thou
12690 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 gh if the INSTEA
126a0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b D OF trigger mak
126b0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 es changes of it
126c0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 s own, those cha
126d0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 nges .** are cou
126e0 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 nted.)^.** ^The
126f0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
12700 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e anges() function
12710 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e counts the chan
12720 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a ges as soon as.*
12730 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 * the statement
12740 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 that makes them
12750 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 is completed (wh
12760 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
12770 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 handle.** is pa
12780 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
12790 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
127a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
127b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
127c0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
127d0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
127e0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
127f0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
12800 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f ma], and the [to
12810 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 tal_changes() SQ
12820 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
12830 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
12840 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
12850 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
12860 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
12870 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
12880 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
12890 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
128a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
128b0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ue.** returned i
128c0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
128d0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
128e0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
128f0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
12900 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
12910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
12920 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
12930 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a nning Query.**.*
12940 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
12950 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
12960 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
12970 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
12980 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
12990 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
129a0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
129b0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
129c0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
129d0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
129e0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
129f0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
12a00 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
12a10 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
12a20 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
12a30 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
12a40 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
12a50 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 ately..**.** ^It
12a60 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
12a70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
12a80 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
12a90 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
12aa0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
12ab0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
12ac0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
12ad0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
12ae0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
12af0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
12b00 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
12b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12b20 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
12b30 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
12b40 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
12b50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
12b60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
12b70 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
12b80 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
12b90 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
12ba0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
12bb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
12bc0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
12bd0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
12be0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
12bf0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
12c00 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
12c10 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
12c20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
12c30 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 * ^An SQL operat
12c40 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
12c50 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
12c60 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
12c70 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 RRUPT]..** ^If t
12c80 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
12c90 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
12ca0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
12cb0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
12cc0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
12cd0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
12ce0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
12cf0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
12d00 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
12d10 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
12d20 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
12d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
12d40 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
12d50 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
12d60 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
12d70 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
12d80 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
12d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12da0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
12db0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 ^Any new SQL sta
12dc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
12dd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
12de0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
12df0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 terrupt() call a
12e00 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a nd before the .*
12e10 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d * running statem
12e20 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 ents reaches zer
12e30 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 o are interrupte
12e40 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 d as if they had
12e50 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 been.** running
12e60 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 prior to the sq
12e70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
12e80 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 ) call. ^New SQ
12e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
12ea0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
12eb0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 after the runni
12ec0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 ng statement cou
12ed0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 nt reaches zero
12ee0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 are.** not effec
12ef0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
12f00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a e3_interrupt()..
12f10 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 ** ^A call to sq
12f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
12f30 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 D) that occurs w
12f40 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f hen there are no
12f50 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
12f60 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 statements is a
12f70 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f no-op and has no
12f80 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
12f90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
12fa0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
12fb0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
12fc0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
12fd0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
12fe0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
12ff0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
13000 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
13010 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
13020 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
13030 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c bad things will
13040 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a likely happen..
13050 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
13060 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 interrupt(sqlite
13070 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
13080 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
13090 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
130a0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a ent Is Complete.
130b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
130c0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 ines are useful
130d0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c during command-l
130e0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 ine input to det
130f0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a ermine if the.**
13100 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
13110 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f ed text seems to
13120 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 form a complete
13130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f SQL statement o
13140 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e r.** if addition
13150 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 al input is need
13160 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e ed before sendin
13170 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a g the text into.
13180 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 ** SQLite for pa
13190 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 rsing. ^These r
131a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 outines return 1
131b0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 if the input st
131c0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 ring.** appears
131d0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 to be a complete
131e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
131f0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 ^A statement is
13200 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a judged to be.**
13210 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 complete if it
13220 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 ends with a semi
13230 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 colon token and
13240 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 is not a prefix
13250 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 of a.** well-for
13260 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 med CREATE TRIGG
13270 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e ER statement. ^
13280 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 Semicolons that
13290 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 are embedded wit
132a0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 hin.** string li
132b0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 terals or quoted
132c0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 identifier name
132d0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 s or comments ar
132e0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e e not.** indepen
132f0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 dent tokens (the
13300 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 y are part of th
13310 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 e token in which
13320 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 they are.** emb
13330 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 edded) and thus
13340 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 do not count as
13350 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d a statement term
13360 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 inator. ^Whites
13370 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d pace.** and comm
13380 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 ents that follow
13390 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 the final semic
133a0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 olon are ignored
133b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
133c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 outines return 0
133d0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
133e0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e t is incomplete.
133f0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 ^If a.** memor
13400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
13410 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f ls, then SQLITE_
13420 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 NOMEM is returne
13430 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
13440 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 routines do not
13450 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 parse the SQL st
13460 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a atements thus.**
13470 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 will not detect
13480 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 syntactically i
13490 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a ncorrect SQL..**
134a0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 .** ^(If SQLite
134b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 has not been ini
134c0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b tialized using [
134d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
134e0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 ze()] prior .**
134f0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 to invoking sqli
13500 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
13510 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e then sqlite3_in
13520 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
13530 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 voked.** automat
13540 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
13550 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 3_complete16().
13560 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c If that initial
13570 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a ization fails,.*
13580 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
13590 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
135a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
135b0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 ) will be non-ze
135c0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 ro.** regardless
135d0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
135e0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c ot the input SQL
135f0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a is complete.)^.
13600 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
13610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
13620 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 lete()] must be
13630 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
13640 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e d.** UTF-8 strin
13650 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 g..**.** The inp
13660 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
13670 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 omplete16()] mus
13680 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
13690 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
136a0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 string in nativ
136b0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f e byte order..*/
136c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
136d0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 plete(const char
136e0 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 *sql);.int sqli
136f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 te3_complete16(c
13700 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b onst void *sql);
13710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13720 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c : Register A Cal
13730 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 lback To Handle
13740 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f SQLITE_BUSY Erro
13750 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 rs.**.** ^This r
13760 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 outine sets a ca
13770 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
13780 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e that might be in
13790 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a voked whenever.*
137a0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 * an attempt is
137b0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 made to open a d
137c0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 atabase table th
137d0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 at another threa
137e0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 d.** or process
137f0 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a has locked..**.*
13800 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 * ^If the busy c
13810 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c allback is NULL,
13820 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 then [SQLITE_BU
13830 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
13840 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
13850 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
13860 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e ediately upon en
13870 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c countering the l
13880 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 ock. ^If the bu
13890 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 sy callback.** i
138a0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
138b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 the callback mi
138c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
138d0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 ith two argument
138e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 s..**.** ^The fi
138f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
13900 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
13910 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
13920 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 e void* pointer
13930 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 which.** is the
13940 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
13950 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 o sqlite3_busy_h
13960 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 andler(). ^The
13970 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
13980 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 to.** the busy h
13990 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
139a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
139b0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 times that the
139c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 busy handler has
139d0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 .** been invoked
139e0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e for this lockin
139f0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
13a00 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
13a10 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
13a20 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
13a30 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
13a40 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
13a50 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
13a60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
13a70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
13a80 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 BLOCKED] is retu
13a90 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 rned..** ^If the
13aa0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
13ab0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
13ac0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
13ad0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
13ae0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
13af0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
13b00 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
13b10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
13b20 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
13b30 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
13b40 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
13b50 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
13b60 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
13b70 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
13b80 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 tion. ^If SQLite
13b90 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
13ba0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
13bb0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
13bc0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
13bd0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
13be0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
13bf0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
13c00 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 SY].** or [SQLIT
13c10 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
13c20 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f instead of invo
13c30 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 king the busy ha
13c40 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
13c50 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
13c60 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
13c70 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
13c80 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
13c90 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
13ca0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
13cb0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
13cc0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
13cd0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
13ce0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
13cf0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
13d00 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
13d10 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
13d20 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
13d30 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
13d40 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
13d50 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
13d60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
13d70 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
13d80 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
13d90 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
13da0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
13db0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
13dc0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
13dd0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
13de0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
13df0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
13e00 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
13e10 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
13e20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
13e30 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
13e40 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
13e50 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
13e60 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
13e70 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
13e80 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
13e90 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
13ea0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
13eb0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
13ec0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 d..**.** ^The de
13ed0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
13ee0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
13ef0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
13f00 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 BUSY] error is c
13f10 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c onverted to [SQL
13f20 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
13f30 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 D].** when SQLit
13f40 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 e is in the midd
13f50 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 le of a large tr
13f60 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 ansaction where
13f70 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 all the.** chang
13f80 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 es will not fit
13f90 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f into the in-memo
13fa0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 ry cache. SQLit
13fb0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 e will.** alread
13fc0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 y hold a RESERVE
13fd0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 D lock on the da
13fe0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 tabase file, but
13ff0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 it needs.** to
14000 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 promote this loc
14010 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 k to EXCLUSIVE s
14020 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 o that it can sp
14030 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 ill cache.** pag
14040 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 es into the data
14050 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 base file withou
14060 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 t harm to concur
14070 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e rent.** readers.
14080 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 ^If it is unab
14090 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 le to promote th
140a0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 e lock, then the
140b0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 in-memory.** ca
140c0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 che will be left
140d0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 in an inconsist
140e0 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f ent state and so
140f0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f the error.** co
14100 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 de is promoted f
14110 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 rom the relative
14120 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 ly benign [SQLIT
14130 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 E_BUSY] to.** th
14140 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 e more severe [S
14150 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
14160 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 KED]. ^This err
14170 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f or code promotio
14180 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 n.** forces an a
14190 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 utomatic rollbac
141a0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 k of the changes
141b0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 . See the.** <a
141c0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f href="/cvstrac/
141d0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f wiki?p=Corruptio
141e0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 nFollowingBusyEr
141f0 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 ror">.** Corrupt
14200 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
14210 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 Error</a> wiki p
14220 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 age for a discus
14230 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 sion of why.** t
14240 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 his is important
14250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
14260 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
14270 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
14280 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
14290 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
142a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
142b0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
142c0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
142d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
142e0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e y set handler.)^
142f0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c ^Note that cal
14300 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 ling [sqlite3_bu
14310 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a sy_timeout()].**
14320 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f will also set o
14330 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 r clear the busy
14340 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 handler..**.**
14350 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 The busy callbac
14360 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b k should not tak
14370 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 e any actions wh
14380 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a ich modify the.*
14390 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
143a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
143b0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
143c0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 ler. Any such a
143d0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 ctions.** result
143e0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
143f0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 havior..** .** A
14400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 busy handler mu
14410 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
14420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
14430 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 tion.** or [prep
14440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
14450 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
14460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
14470 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
14480 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 sy_handler(sqlit
14490 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
144a0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a *,int), void*);.
144b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
144c0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
144d0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 out.**.** ^This
144e0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
144f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
14500 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
14510 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 ler] that sleeps
14520 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 .** for a specif
14530 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 ied amount of ti
14540 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 me when a table
14550 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 is locked. ^The
14560 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c handler.** will
14570 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 sleep multiple
14580 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c times until at l
14590 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
145a0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
145b0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d ng.** have accum
145c0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 ulated. ^After
145d0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
145e0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
145f0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 eeping,.** the h
14600 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 andler returns 0
14610 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 which causes [s
14620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 qlite3_step()] t
14630 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c o return.** [SQL
14640 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
14650 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
14660 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ED]..**.** ^Call
14670 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ing this routine
14680 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e with an argumen
14690 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 t less than or e
146a0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 qual to zero.**
146b0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 turns off all bu
146c0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a sy handlers..**.
146d0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
146e0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
146f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 busy handler for
14700 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
14710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
14720 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 ction] any any g
14730 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 iven moment. If
14740 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 another busy ha
14750 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 ndler.** was def
14760 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 ined (using [sq
14770 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
14780 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 er()]) prior to
14790 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 calling.** this
147a0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 routine, that ot
147b0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
147c0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a is cleared.)^.*
147d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
147e0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 sy_timeout(sqlit
147f0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f e3*, int ms);../
14800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
14810 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 onvenience Routi
14820 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 nes For Running
14830 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Queries.**.** Th
14840 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
14850 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
14860 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
14870 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
14880 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
14890 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
148a0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
148b0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
148c0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
148d0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
148e0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
148f0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
14900 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
14910 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
14920 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
14930 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
14940 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
14950 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
14960 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
14970 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
14980 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
14990 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
149a0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
149b0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
149c0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
149d0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
149e0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
149f0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
14a00 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
14a10 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
14a20 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
14a30 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
14a40 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
14a50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
14a60 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
14a70 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
14a80 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
14a90 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
14aa0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
14ab0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
14ac0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
14ad0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
14ae0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
14af0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
14b00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
14b10 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
14b20 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
14b30 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
14b40 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
14b50 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
14b60 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
14b70 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
14b80 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
14b90 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
14ba0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
14bb0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
14bc0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
14bd0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
14be0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
14bf0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
14c00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
14c10 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
14c20 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
14c30 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
14c40 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
14c50 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
14c60 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
14c70 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
14c80 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
14c90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
14ca0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
14cb0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
14cc0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
14cd0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
14ce0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
14cf0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
14d00 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
14d10 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
14d20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
14d30 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
14d40 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
14d50 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
14d60 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
14d70 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
14d80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14d90 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
14da0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
14db0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
14dc0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
14dd0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
14de0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
14df0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
14e00 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
14e10 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
14e20 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
14e30 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
14e40 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
14e50 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
14e60 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
14e70 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
14e80 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
14e90 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
14ea0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
14eb0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
14ec0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
14ed0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
14ee0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
14ef0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
14f00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
14f10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
14f20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
14f30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
14f40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
14f50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
14f60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
14f70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
14f80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
14f90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
14fa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
14fb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
14fc0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
14fd0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
14fe0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
14ff0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
15000 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
15010 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
15020 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
15030 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
15040 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
15050 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
15060 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
15070 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
15080 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
15090 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
150a0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
150b0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
150c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
150d0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
150e0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
150f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
15100 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
15110 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
15120 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
15130 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
15140 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
15150 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
15160 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
15170 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
15180 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
15190 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
151a0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
151b0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
151c0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
151d0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
151e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
151f0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
15200 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
15210 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
15220 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
15230 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
15240 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
15250 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
15260 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
15270 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
15280 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
15290 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
152a0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
152b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
152c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
152d0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
152e0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
152f0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
15300 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
15310 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
15320 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
15330 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
15340 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
15350 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
15360 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
15370 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
15380 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
15390 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
153a0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
153b0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
153c0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
153d0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
153e0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
153f0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
15400 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
15410 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
15420 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
15430 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
15440 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
15450 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
15460 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
15470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 .int sqlite3_get
15480 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 _table(. sqlite
15490 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
154a0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
154b0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
154c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f har *zSql, /
154d0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
154e0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 uated */. char
154f0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 ***pazResult,
15500 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 /* Results of t
15510 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e he query */. in
15520 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 t *pnRow,
15530 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
15540 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 result rows wri
15550 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 tten here */. i
15560 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 nt *pnColumn,
15570 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
15580 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
15590 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
155a0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d . char **pzErrm
155b0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f sg /* Erro
155c0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
155d0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 re */.);.void sq
155e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
155f0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b (char **result);
15600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
15610 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 : Formatted Stri
15620 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 ng Printing Func
15630 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
15640 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
15650 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 ork-alikes of th
15660 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
15670 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
15680 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
15690 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
156a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
156b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
156c0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
156d0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
156e0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
156f0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
15700 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
15710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
15720 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
15730 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
15740 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
15750 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
15760 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
15770 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
15780 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
15790 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
157a0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
157b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
157c0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
157d0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
157e0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
157f0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
15800 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 **.** ^(In sqlit
15810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
15820 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
15830 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
15840 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
15850 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
15860 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
15870 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
15880 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
15890 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
158a0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
158b0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
158c0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
158d0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
158e0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
158f0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
15900 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
15910 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
15920 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 nprintf().)^ Th
15930 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 is is an.** hist
15940 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 orical accident
15950 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 that cannot be f
15960 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 ixed without bre
15970 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 aking.** backwar
15980 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
15990 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 . ^(Note also t
159a0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
159b0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
159c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
159d0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
159e0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
159f0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
15a00 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
15a10 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
15a20 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 r.)^ We admit t
15a30 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
15a40 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
15a50 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
15a60 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
15a70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
15a80 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
15a90 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
15aa0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
15ab0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
15ac0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
15ad0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
15ae0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f ty..**.** ^As lo
15af0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
15b00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
15b10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
15b20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
15b30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
15b40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
15b50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
15b60 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 inated. ^The fi
15b70 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
15b80 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
15b90 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
15ba0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
15bb0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
15bc0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
15bd0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
15be0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
15bf0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
15c00 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
15c10 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
15c20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
15c30 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
15c40 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
15c50 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
15c60 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
15c70 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
15c80 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
15c90 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
15ca0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
15cb0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
15cc0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
15cd0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
15ce0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
15cf0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e e "%q", "%Q", an
15d00 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a d "%z" options..
15d10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f **.** ^(The %q o
15d20 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
15d30 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
15d40 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
15d50 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
15d60 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
15d70 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
15d80 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
15d90 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
15da0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
15db0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
15dc0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
15dd0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 ing literal.)^
15de0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
15df0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
15e00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
15e10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
15e20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
15e30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
15e40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
15e50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
15e60 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
15e70 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
15e80 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
15e90 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
15ea0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
15eb0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
15ec0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
15ed0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
15ee0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
15ef0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
15f00 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
15f10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
15f20 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
15f30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
15f40 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
15f50 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
15f60 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
15f70 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
15f80 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
15f90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
15fa0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
15fb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
15fc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
15fd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
15fe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
15ff0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
16000 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
16010 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
16020 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
16030 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
16040 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
16050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
16060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
16070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
16080 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
16090 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
160a0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
160b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
160c0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
160d0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
160e0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
160f0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
16100 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
16110 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
16120 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
16130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
16140 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
16150 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
16160 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
16170 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
16180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
16190 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
161a0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
161b0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
161c0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
161d0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
161e0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
161f0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
16200 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
16210 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
16220 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 iteral..**.** ^(
16230 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f The %Q option wo
16240 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 rks like %q exce
16250 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 pt it also adds
16260 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 single quotes ar
16270 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 ound.** the outs
16280 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c ide of the total
16290 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 string. Additi
162a0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 onally, if the p
162b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a arameter in the.
162c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 ** argument list
162d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
162e0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 er, %Q substitut
162f0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c es the text "NUL
16300 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 L" (without.** s
16310 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e ingle quotes).)^
16320 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
16330 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
16340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
16350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
16360 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
16370 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
16380 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
16390 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
163a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
163b0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
163c0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
163d0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
163e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
163f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
16400 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
16410 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
16420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
16430 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
16440 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
16450 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
16460 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
16470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 nter..**.** ^(Th
16480 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
16490 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
164a0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
164b0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
164c0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
164d0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
164e0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
164f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
16500 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
16510 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
16520 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
16530 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a ing.)^.*/.char *
16540 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
16550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 const char*,...)
16560 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
16570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
16580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
16590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e char *sqlite3_sn
165a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
165b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e ,const char*, ..
165c0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
165d0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
165e0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d cation Subsystem
165f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
16600 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
16610 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
16620 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
16630 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
16640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
16650 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
16660 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
16670 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
16680 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
16690 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
166a0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
166b0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
166c0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
166d0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
166e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
166f0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
16700 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
16710 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
16720 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
16730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
16740 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
16750 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
16760 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
16770 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
16780 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 ameter..** ^If s
16790 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
167a0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
167b0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
167c0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
167d0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
167e0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 pointer. ^If t
167f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 he parameter N t
16800 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c o.** sqlite3_mal
16810 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
16820 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 negative then s
16830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
16840 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c returns.** a NUL
16850 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
16860 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
16870 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
16880 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
16890 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
168a0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
168b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
168c0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
168d0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
168e0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
168f0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 be reused. ^Th
16900 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 e sqlite3_free()
16910 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 routine is.** a
16920 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c no-op if is cal
16930 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
16940 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e pointer. Passin
16950 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
16960 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 .** to sqlite3_f
16970 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 ree() is harmles
16980 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 s. After being
16990 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a freed, memory.**
169a0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 should neither
169b0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 be read nor writ
169c0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 ten. Even readi
169d0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 ng previously fr
169e0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 eed.** memory mi
169f0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 ght result in a
16a00 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
16a10 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 lt or other seve
16a20 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d re error..** Mem
16a30 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 ory corruption,
16a40 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
16a50 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 ault, or other s
16a60 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d evere error.** m
16a70 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 ight result if s
16a80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
16a90 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e called with a n
16aa0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 on-NULL pointer
16ab0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 that.** was not
16ac0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
16ad0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
16ae0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
16af0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 c()..**.** ^(The
16b00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
16b10 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
16b20 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 empts to resize
16b30 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 a.** prior memor
16b40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
16b50 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
16b60 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 tes, where N is
16b70 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 the.** second pa
16b80 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 rameter. The me
16b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
16ba0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 to be resized is
16bb0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 the first.** pa
16bc0 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 rameter.)^ ^ If
16bd0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
16be0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
16bf0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
16c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
16c10 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 en its behavior
16c20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
16c30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
16c40 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 e3_malloc(N) whe
16c50 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
16c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
16c70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
16c80 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 )..** ^If the se
16c90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
16ca0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
16cb0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a c() is zero or.*
16cc0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
16cd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
16ce0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
16cf0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
16d00 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 qlite3_free(P) w
16d10 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 here P is the fi
16d20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
16d30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
16d40 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f ()..** ^sqlite3_
16d50 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
16d60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
16d70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16d80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 on.** of at leas
16d90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a t N bytes in siz
16da0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 e or NULL if suf
16db0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 ficient memory i
16dc0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
16dd0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 * ^If M is the s
16de0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
16df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
16e00 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
16e10 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
16e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
16e30 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
16e40 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
16e50 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
16e60 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
16e70 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 oc() and the pri
16e80 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
16e90 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 freed..** ^If s
16ea0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
16eb0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
16ec0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c hen the prior al
16ed0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e location.** is n
16ee0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
16ef0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
16f00 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
16f10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c malloc() and sql
16f20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
16f30 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
16f40 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
16f50 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
16f60 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
16f70 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
16f80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
16f90 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
16fa0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
16fb0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
16fc0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
16fd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
16fe0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
16ff0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
17000 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
17010 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
17020 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
17030 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
17040 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
17050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
17060 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
17070 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
17080 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
17090 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
170a0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
170b0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
170c0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
170d0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 e used..**.** Th
170e0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
170f0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
17100 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d ls.** the system
17110 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
17120 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 ee() directly wh
17130 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a en converting.**
17140 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 filenames betwe
17150 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 en the UTF-8 enc
17160 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 oding used by SQ
17170 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 Lite.** and what
17180 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e ever filename en
17190 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 coding is used b
171a0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 y the particular
171b0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 Windows.** inst
171c0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 allation. Memor
171d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
171e0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 ors are detected
171f0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 , but.** they ar
17200 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
17210 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
17220 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
17230 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
17240 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
17250 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
17260 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
17270 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
17280 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
17290 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
172a0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
172b0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
172c0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
172d0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
172e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
172f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
17300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
17310 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
17320 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
17330 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
17340 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
17350 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
17360 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
17370 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
17380 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
17390 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
173a0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
173b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
173c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
173d0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 c()]..*/.void *s
173e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e qlite3_malloc(in
173f0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 t);.void *sqlite
17400 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 3_realloc(void*,
17410 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
17420 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b te3_free(void*);
17430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17440 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
17450 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
17460 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
17470 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
17480 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
17490 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
174a0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
174b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
174c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
174d0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
174e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
174f0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
17500 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
17510 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
17520 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
17530 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
17540 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
17550 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
17560 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
17570 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
17580 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
17590 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
175a0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
175b0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
175c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
175d0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
175e0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
175f0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
17600 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
17610 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
17620 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
17630 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
17640 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
17650 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
17660 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
17670 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
17680 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
17690 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
176a0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
176b0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
176c0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
176d0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
176e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
176f0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
17700 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
17710 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
17720 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
17730 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
17740 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
17750 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
17760 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
17770 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
17780 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
17790 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
177a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
177b0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
177c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
177d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
177e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
177f0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
17800 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
17810 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
17820 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
17830 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
17840 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
17850 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
17860 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
17870 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
17880 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
17890 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
178a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
178b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
178c0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
178d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
178e0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
178f0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
17900 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
17910 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
17920 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
17930 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
17940 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
17950 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
17960 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
17970 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
17980 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
17990 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
179a0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
179b0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
179c0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
179d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
179e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
179f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
17a00 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
17a10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
17a20 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
17a30 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
17a40 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
17a50 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
17a60 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
17a70 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
17a80 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
17a90 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
17aa0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
17ab0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
17ac0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 .** ^The first t
17ad0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ime this routine
17ae0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 is invoked (eit
17af0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f her internally o
17b00 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c r by.** the appl
17b10 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e ication) the PRN
17b20 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e G is seeded usin
17b30 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
17b40 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 ained.** from th
17b50 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 e xRandomness me
17b60 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
17b70 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
17b80 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e ] object..** ^On
17b90 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 all subsequent
17ba0 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 invocations, the
17bb0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
17bc0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a ss is generated.
17bd0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e ** internally an
17be0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 d without recour
17bf0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 se to the [sqlit
17c00 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e e3_vfs] xRandomn
17c10 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a ess.** method..*
17c20 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
17c30 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c andomness(int N,
17c40 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a void *P);../*.*
17c50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
17c60 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 ile-Time Authori
17c70 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 zation Callbacks
17c80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
17c90 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
17ca0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17cb0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
17cc0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
17cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
17ce0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
17cf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
17d00 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
17d10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
17d20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
17d30 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
17d40 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
17d50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
17d60 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
17d70 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
17d80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
17d90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
17da0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
17db0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
17dc0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
17dd0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
17de0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
17df0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
17e00 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
17e10 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
17e20 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
17e30 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
17e40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
17e50 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
17e60 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
17e70 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
17e80 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
17e90 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
17ea0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
17eb0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
17ec0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
17ed0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
17ee0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
17ef0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
17f00 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
17f10 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
17f20 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
17f30 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
17f40 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
17f50 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
17f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
17f70 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
17f80 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
17f90 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
17fa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
17fb0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
17fc0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
17fd0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
17fe0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
17ff0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
18000 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
18010 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
18020 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
18030 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
18040 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
18050 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
18060 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
18070 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
18080 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
18090 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
180a0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
180b0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
180c0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
180d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
180e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
180f0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
18100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
18110 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
18120 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
18130 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
18140 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
18150 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
18160 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
18170 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
18180 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
18190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
181a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
181b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
181c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
181d0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
181e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
181f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
18200 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
18210 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
18220 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
18230 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
18240 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
18250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
18260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
18270 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
18280 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
18290 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
182a0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
182b0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
182c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
182d0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
182e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
182f0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
18300 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
18310 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
18320 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
18330 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
18340 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
18350 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
18360 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
18370 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
18380 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
18390 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
183a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
183b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
183c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
183d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
183e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
183f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
18400 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
18410 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
18420 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
18430 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
18440 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
18450 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
18460 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
18470 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
18480 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
18490 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
184a0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
184b0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
184c0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
184d0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
184e0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
184f0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
18500 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
18510 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
18520 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
18530 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
18540 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
18550 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
18560 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
18570 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
18580 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
18590 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
185a0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
185b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
185c0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
185d0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
185e0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
185f0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
18600 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
18610 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
18620 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
18630 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
18640 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
18650 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
18660 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
18670 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
18680 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
18690 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
186a0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
186b0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
186c0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
186d0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
186e0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
186f0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
18700 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
18710 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
18720 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
18730 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
18740 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
18750 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
18760 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
18770 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
18780 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
18790 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
187a0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
187b0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
187c0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
187d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
187e0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
187f0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
18800 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
18810 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
18820 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
18830 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
18840 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
18850 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
18860 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
18870 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
18880 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
18890 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
188a0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
188b0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
188c0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
188d0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
188e0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
188f0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
18900 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
18910 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
18920 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
18930 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
18940 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
18950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18960 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
18970 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
18980 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
18990 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
189a0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
189b0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
189c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
189d0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
189e0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
189f0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
18a00 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
18a10 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
18a20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
18a30 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
18a40 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
18a50 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
18a60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
18a70 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
18a80 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
18a90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
18aa0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
18ab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
18ac0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
18ad0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
18ae0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
18af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
18b00 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
18b10 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
18b20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
18b30 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
18b40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
18b50 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
18b60 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
18b70 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
18b80 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
18b90 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
18ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
18bb0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
18bc0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
18bd0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
18be0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
18bf0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
18c00 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
18c10 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
18c20 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
18c30 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
18c40 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
18c50 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
18c60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
18c70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
18c80 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
18c90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
18ca0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
18cb0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
18cc0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
18cd0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
18ce0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
18cf0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
18d00 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
18d10 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
18d20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
18d30 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
18d40 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
18d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
18d60 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
18d70 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
18d80 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
18d90 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
18da0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
18db0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
18dc0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
18dd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
18de0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
18df0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
18e00 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
18e10 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
18e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
18e30 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
18e40 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
18e50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
18e60 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
18e70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
18e80 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
18e90 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
18ea0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
18eb0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
18ec0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
18ed0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
18ee0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
18ef0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
18f00 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
18f10 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
18f20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
18f30 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
18f40 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
18f50 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
18f60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
18f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
18f80 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f ENY 1 /* Abo
18f90 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
18fa0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 ment with an err
18fb0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
18fc0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 LITE_IGNORE 2
18fd0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 /* Don't allow a
18fe0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 ccess, but don't
18ff0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 generate an err
19000 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 or */../*.** CAP
19010 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
19020 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a r Action Codes.*
19030 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
19040 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
19050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
19060 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
19070 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 ck function.** t
19080 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 hat is invoked t
19090 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 o authorize cert
190a0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ain SQL statemen
190b0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a t actions. The.
190c0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
190d0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
190e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
190f0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 r code that spec
19100 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 ifies.** what ac
19110 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 tion is being au
19120 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 thorized. These
19130 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 are the integer
19140 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 action codes th
19150 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 at.** the author
19160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 izer callback ma
19170 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a y be passed..**.
19180 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 ** These action
19190 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e code values sign
191a0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 ify what kind of
191b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f operation is to
191c0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 be.** authorize
191d0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 d. The 3rd and
191e0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 4th parameters t
191f0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 o the authorizat
19200 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 ion.** callback
19210 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 function will be
19220 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
19230 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
19240 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a which of these.
19250 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 ** codes is used
19260 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
19270 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 arameter. ^(The
19280 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
19290 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 o the.** authori
192a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
192b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
192c0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 database ("main"
192d0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 , "temp",.** etc
192e0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
192f0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 .)^ ^The 6th pa
19300 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
19310 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19320 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d ck.** is the nam
19330 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d e of the inner-m
19340 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 ost trigger or v
19350 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 iew that is resp
19360 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 onsible for.** t
19370 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
19380 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
19390 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
193a0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
193b0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 m.** top-level S
193c0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a QL code..*/./***
193d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
193e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
193f0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a ******** 3rd ***
19400 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a ********* 4th **
19410 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 *********/.#defi
19420 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
19430 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
19440 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 1 /* Index Nam
19450 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
19460 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
19470 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
19480 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
19490 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
194a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
194b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
194c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
194d0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 EMP_INDEX 3
194e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
194f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
19500 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
19510 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
19520 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 MP_TABLE 4
19530 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
19540 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
19550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
19560 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
19570 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 P_TRIGGER 5
19580 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
19590 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
195a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
195b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
195c0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f _VIEW 6 /
195d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
195e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
195f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
19600 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 ITE_CREATE_TRIGG
19610 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a ER 7 /*
19620 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
19630 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
19640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19650 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 TE_CREATE_VIEW
19660 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 8 /*
19670 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
19680 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
19690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
196a0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 E_DELETE
196b0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 9 /* T
196c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
196d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
196e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
196f0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 _DROP_INDEX
19700 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 10 /* In
19710 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
19720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
19730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19740 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 DROP_TABLE
19750 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 11 /* Tab
19760 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
19770 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
19780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
19790 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ROP_TEMP_INDEX
197a0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 12 /* Inde
197b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
197c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
197d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
197e0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 OP_TEMP_TABLE
197f0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 13 /* Table
19800 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
19810 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
19820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
19830 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 P_TEMP_TRIGGER
19840 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 14 /* Trigge
19850 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
19860 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
19870 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
19880 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
19890 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 15 /* View Na
198a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
198b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
198c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
198d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 TRIGGER
198e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 16 /* Trigger
198f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
19900 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
19910 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
19920 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 IEW 1
19930 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 7 /* View Name
19940 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
19950 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
19960 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 e SQLITE_INSERT
19970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 18
19980 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
19990 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
199a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
199b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 SQLITE_PRAGMA
199c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 19
199d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 /* Pragma Name
199e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 1st arg or
199f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 NULL */.#define
19a00 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 SQLITE_READ
19a10 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20
19a20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
19a30 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
19a40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
19a50 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 QLITE_SELECT
19a60 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 21
19a70 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
19a80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
19a90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
19aa0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e LITE_TRANSACTION
19ab0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 22 /
19ac0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
19ad0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
19ae0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
19af0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 ITE_UPDATE
19b00 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 23 /*
19b10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
19b20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
19b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19b40 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 TE_ATTACH
19b50 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 24 /*
19b60 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 Filename
19b70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
19b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
19b90 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 E_DETACH
19ba0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 25 /* D
19bb0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e atabase Name N
19bc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
19bd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19be0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 _ALTER_TABLE
19bf0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 26 /* Da
19c00 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 tabase Name Ta
19c10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19c30 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 REINDEX
19c40 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 27 /* Ind
19c50 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c ex Name NUL
19c60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
19c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
19c80 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 NALYZE
19c90 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 28 /* Tabl
19ca0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
19cb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
19cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
19cd0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 EATE_VTABLE
19ce0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 29 /* Table
19cf0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
19d00 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
19d20 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 P_VTABLE
19d30 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 30 /* Table
19d40 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
19d50 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 fine SQLITE_FUNC
19d70 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 TION
19d80 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 31 /* NULL
19d90 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f Functio
19da0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 n Name */.#def
19db0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 ine SQLITE_SAVEP
19dc0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 OINT
19dd0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 32 /* Operatio
19de0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e n Savepoin
19df0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 t Name */.#defi
19e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 ne SQLITE_COPY
19e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19e20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 0 /* No longer
19e30 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 used */../*.**
19e40 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
19e50 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
19e60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
19e70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
19e80 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
19e90 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
19ea0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
19eb0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
19ec0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
19ed0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
19ee0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
19ef0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
19f00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
19f10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
19f20 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
19f30 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
19f40 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
19f50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
19f60 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
19f70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
19f80 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
19f90 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
19fa0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
19fb0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
19fc0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
19fd0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
19fe0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
19ff0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
1a000 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
1a010 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
1a020 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
1a030 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
1a040 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
1a050 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
1a060 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
1a070 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
1a080 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
1a090 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
1a0a0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
1a0b0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
1a0c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
1a0d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
1a0e0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
1a0f0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 te3_profile() is
1a100 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 invoked.** as e
1a110 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
1a120 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 t finishes. ^Th
1a130 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
1a140 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
1a150 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
1a160 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
1a170 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
1a180 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
1a190 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
1a1a0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
1a1b0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 to run. ^The p
1a1c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a rofile callback.
1a1d0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e ** time is in un
1a1e0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e its of nanosecon
1a1f0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 ds, however the
1a200 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e current implemen
1a210 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c tation.** is onl
1a220 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c y capable of mil
1a230 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 lisecond resolut
1a240 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c ion so the six l
1a250 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
1a260 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 .** digits in th
1a270 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 e time are meani
1a280 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 ngless. Future
1a290 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1a2a0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 te.** might prov
1a2b0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f ide greater reso
1a2c0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 lution on the pr
1a2d0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e ofiler callback.
1a2e0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
1a2f0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 _profile() funct
1a300 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 ion is considere
1a310 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 d experimental a
1a320 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 nd is.** subject
1a330 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 to change in fu
1a340 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
1a350 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 SQLite..*/.void
1a360 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 *sqlite3_trace(
1a370 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
1a380 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
1a390 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
1a3a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 *);.SQLITE_EXPER
1a3b0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 IMENTAL void *sq
1a3c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
1a3d0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
1a3e0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
1a3f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
1a400 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
1a410 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1a420 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f I3REF: Query Pro
1a430 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a gress Callbacks.
1a440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1a450 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
1a460 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 ler(D,N,X,P) int
1a470 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
1a480 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 e callback.** fu
1a490 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 nction X to be i
1a4a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 nvoked periodica
1a4b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 lly during long
1a4c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f running calls to
1a4d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
1a4e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 c()], [sqlite3_s
1a4f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tep()] and [sqli
1a500 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
1a510 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 for.** database
1a520 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
1a530 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
1a540 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
1a550 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
1a560 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
1a570 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
1a580 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ry..**.** ^The p
1a590 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 arameter P is pa
1a5a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
1a5b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
1a5c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 er to the .** ca
1a5d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1a5e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 X. ^The paramet
1a5f0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 er N is the numb
1a600 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 er of .** [virtu
1a610 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 al machine instr
1a620 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 uctions] that ar
1a630 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 e evaluated betw
1a640 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a een successive.*
1a650 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
1a660 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e the callback X.
1a670 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 .**.** ^Only a s
1a680 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 ingle progress h
1a690 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 andler may be de
1a6a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d fined at one tim
1a6b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 e per.** [databa
1a6c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 se connection];
1a6d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 setting a new pr
1a6e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 ogress handler c
1a6f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c ancels the.** ol
1a700 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 d one. ^Setting
1a710 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 parameter X to
1a720 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 NULL disables th
1a730 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1a740 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 er..** ^The prog
1a750 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 ress handler is
1a760 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 also disabled by
1a770 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 setting N to a
1a780 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 value less.** th
1a790 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 an 1..**.** ^If
1a7a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
1a7b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
1a7c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 n-zero, the oper
1a7d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 ation is.** inte
1a7e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 rrupted. This f
1a7f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 eature can be us
1a800 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
1a810 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 a.** "Cancel" bu
1a820 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 tton on a GUI pr
1a830 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f ogress dialog bo
1a840 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f x..**.** The pro
1a850 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
1a860 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
1a870 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
1a880 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
1a890 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1a8a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1a8b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 oked the progres
1a8c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f s handler..** No
1a8d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
1a8e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1a8f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
1a900 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
1a910 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
1a920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
1a930 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
1a940 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
1a950 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
1a960 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
1a970 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
1a980 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 (sqlite3*, int,
1a990 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
1a9a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1a9b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 PI3REF: Opening
1a9c0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 A New Database C
1a9d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onnection.**.**
1a9e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1a9f0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
1aa00 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f atabase file who
1aa10 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e se name is given
1aa20 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e by the.** filen
1aa30 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
1aa40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
1aa50 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
1aa60 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
1aa70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1aa80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
1aa90 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
1aaa0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
1aab0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
1aac0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
1aad0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
1aae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1aaf0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
1ab00 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
1ab10 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
1ab20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
1ab30 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
1ab40 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
1ab50 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
1ab60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1ab70 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
1ab80 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
1ab90 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
1aba0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
1abb0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
1abc0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
1abd0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
1abe0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
1abf0 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
1ac00 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
1ac10 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
1ac20 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
1ac30 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
1ac40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
1ac50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
1ac60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
1ac70 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
1ac80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1ac90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
1aca0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
1acb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
1acc0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
1acd0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
1ace0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
1acf0 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
1ad00 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
1ad10 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
1ad20 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
1ad30 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
1ad40 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
1ad50 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
1ad60 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
1ad70 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f if.** sqlite3_o
1ad80 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
1ad90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 _open_v2() is ca
1ada0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
1adb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
1adc0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 byte order if s
1add0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 qlite3_open16()
1ade0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
1adf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
1ae00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
1ae10 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
1ae20 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 resources.** as
1ae30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
1ae40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
1ae50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 ection] handle s
1ae60 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
1ae70 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 d by.** passing
1ae80 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
1ae90 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 lose()] when it
1aea0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 is no longer req
1aeb0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
1aec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1aed0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 () interface wor
1aee0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
1aef0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 open().** except
1af00 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 that it accepts
1af10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
1af20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 parameters for a
1af30 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f dditional contro
1af40 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 l.** over the ne
1af50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
1af60 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c ction. ^(The fl
1af70 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
1af80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1af90 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f _v2() can take o
1afa0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c ne of.** the fol
1afb0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c lowing three val
1afc0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 ues, optionally
1afd0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 combined with th
1afe0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 e .** [SQLITE_OP
1aff0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
1b000 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
1b010 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
1b020 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c EN_SHAREDCACHE],
1b030 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 .** and/or [SQLI
1b040 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1b050 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a ACHE] flags:)^.*
1b060 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
1b070 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
1b080 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
1b090 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1b0a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
1b0b0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
1b0c0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1b0d0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
1b0e0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
1b0f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1b100 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1b110 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
1b120 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
1b130 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1b140 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1b150 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1b160 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
1b170 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
1b180 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
1b190 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
1b1a0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
1b1b0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
1b1c0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
1b1d0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1b1e0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
1b1f0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
1b200 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1b210 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
1b220 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
1b230 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
1b240 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
1b250 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
1b260 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
1b270 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1b280 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1b290 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 , and is creates
1b2a0 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 it if.** it doe
1b2b0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 s not already ex
1b2c0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 ist. This is the
1b2d0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 behavior that i
1b2e0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f s always used fo
1b2f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
1b300 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
1b310 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e open16().</dd>)^
1b320 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </dl>.**.**
1b330 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
1b340 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1b350 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 open_v2() is not
1b360 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 one of the.** c
1b370 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 ombinations show
1b380 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f n above or one o
1b390 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f f the combinatio
1b3a0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 ns shown above c
1b3b0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 ombined.** with
1b3c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
1b3d0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 _NOMUTEX], [SQLI
1b3e0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
1b3f0 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f X],.** [SQLITE_O
1b400 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
1b410 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
1b420 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
1b430 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 E] flags,.** the
1b440 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
1b450 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
1b460 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
1b470 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
1b480 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
1b490 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1b4a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
1b4b0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
1b4c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
1b4d0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
1b4e0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
1b4f0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
1b500 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
1b510 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
1b520 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
1b530 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
1b540 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
1b550 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
1b560 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
1b570 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
1b580 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
1b590 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
1b5a0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
1b5b0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
1b5c0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
1b5d0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
1b5e0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
1b5f0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
1b600 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
1b610 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
1b620 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
1b630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
1b640 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
1b650 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
1b660 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
1b670 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
1b680 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
1b690 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
1b6a0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1b6b0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
1b6c0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
1b6d0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
1b6e0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
1b6f0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
1b700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b710 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
1b720 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
1b730 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
1b740 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
1b750 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 led..**.** ^If t
1b760 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 he filename is "
1b770 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 :memory:", then
1b780 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
1b790 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 rary in-memory d
1b7a0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 atabase.** is cr
1b7b0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f eated for the co
1b7c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 nnection. ^This
1b7d0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
1b7e0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
1b7f0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
1b800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b810 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
1b820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1b830 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
1b840 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
1b850 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
1b860 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
1b870 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
1b880 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
1b890 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
1b8a0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
1b8b0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
1b8c0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
1b8d0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
1b8e0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
1b8f0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
1b900 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
1b910 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
1b920 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
1b930 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
1b940 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
1b950 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 ame is an empty
1b960 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 string, then a p
1b970 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
1b980 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 y.** on-disk dat
1b990 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 abase will be cr
1b9a0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 eated. ^This pr
1b9b0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 ivate database w
1b9c0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 ill be.** automa
1b9d0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 tically deleted
1b9e0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 as soon as the d
1b9f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ba00 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a on is closed..**
1ba10 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
1ba20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1ba30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
1ba40 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1ba50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
1ba60 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
1ba70 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
1ba80 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
1ba90 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
1baa0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
1bab0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
1bac0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 use. ^If the f
1bad0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1bae0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
1baf0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
1bb00 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
1bb10 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
1bb20 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
1bb30 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
1bb40 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
1bb50 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
1bb60 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
1bb70 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
1bb80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1bb90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1bba0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
1bbb0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
1bbc0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
1bbd0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
1bbe0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
1bbf0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
1bc00 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
1bc10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
1bc20 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
1bc30 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
1bc40 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
1bc50 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
1bc60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f e3_open_v2()..*/
1bc70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
1bc80 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 n(. const char
1bc90 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
1bca0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
1bcb0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
1bcc0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
1bcd0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
1bce0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
1bcf0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
1bd00 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 3_open16(. cons
1bd10 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 t void *filename
1bd20 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
1bd30 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 filename (UTF-16
1bd40 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
1bd50 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
1bd60 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
1bd70 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e handle */.);.in
1bd80 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
1bd90 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
1bda0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
1bdb0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
1bdc0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
1bdd0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
1bde0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
1bdf0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
1be00 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
1be10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1be20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
1be30 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
1be40 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
1be50 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
1be60 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
1be70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
1be80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a es And Messages.
1be90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1bea0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 e3_errcode() int
1beb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
1bec0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
1bed0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b lt code] or.** [
1bee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
1bef0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f code] for the mo
1bf00 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 st recent failed
1bf10 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
1bf20 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 all.** associate
1bf30 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
1bf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
1bf50 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 If a prior API c
1bf60 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 all failed.** bu
1bf70 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
1bf80 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 t API call succe
1bf90 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e eded, the return
1bfa0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 value from.** s
1bfb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
1bfc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
1bfd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
1bfe0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
1bff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
1c000 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
1c010 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
1c020 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
1c030 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
1c040 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
1c050 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
1c060 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
1c070 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
1c080 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
1c090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
1c0a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
1c0b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
1c0c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
1c0d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
1c0e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
1c0f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
1c100 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
1c110 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
1c120 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
1c130 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
1c140 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
1c150 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
1c160 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
1c170 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
1c180 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
1c190 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
1c1a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
1c1b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
1c1c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
1c1d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
1c1e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
1c1f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
1c200 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
1c210 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 )^.**.** When th
1c220 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
1c230 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
1c240 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
1c250 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
1c260 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
1c270 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
1c280 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
1c290 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
1c2a0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
1c2b0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
1c2c0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
1c2d0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1c2e0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
1c2f0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
1c300 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
1c310 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
1c320 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
1c330 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
1c340 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
1c350 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
1c360 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
1c370 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
1c380 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
1c390 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
1c3a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
1c3b0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
1c3c0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
1c3d0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
1c3e0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
1c3f0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
1c400 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
1c410 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
1c420 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
1c430 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
1c440 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
1c450 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
1c460 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
1c470 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
1c480 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
1c490 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
1c4a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
1c4b0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
1c4c0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
1c4d0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
1c4e0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
1c4f0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
1c500 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
1c510 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
1c520 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
1c530 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e ot be set..*/.in
1c540 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
1c550 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
1c560 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
1c570 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
1c580 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 ite3 *db);.const
1c590 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
1c5a0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
1c5b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
1c5c0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 ite3_errmsg16(sq
1c5d0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1c5e0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 CAPI3REF: SQL St
1c5f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
1c600 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
1c610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
1c620 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
1c630 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
1c640 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
1c650 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
1c660 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
1c670 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
1c680 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 is object is var
1c690 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 iously known as
1c6a0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 a "prepared stat
1c6b0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 ement" or a.** "
1c6c0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 compiled SQL sta
1c6d0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c tement" or simpl
1c6e0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e y as a "statemen
1c6f0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 t"..**.** The li
1c700 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
1c710 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
1c720 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
1c730 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
1c740 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
1c750 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1c760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c770 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
1c780 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
1c790 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
1c7a0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 values to [host
1c7b0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 parameters] usi
1c7c0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
1c7d0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 ind_*().**
1c7e0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c interfaces..** <
1c7f0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 li> Run the SQL
1c800 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
1c810 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 te3_step()] one
1c820 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
1c830 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 * <li> Reset the
1c840 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1c850 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1c860 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a )] then go back.
1c870 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 ** to step
1c880 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 2. Do this zero
1c890 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1c8a0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 ** <li> Destroy
1c8b0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
1c8c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1c8d0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a ze()]..** </ol>.
1c8e0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 **.** Refer to d
1c8f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 ocumentation on
1c900 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f individual metho
1c910 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 ds above for add
1c920 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1c930 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
1c940 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1c950 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 3_stmt sqlite3_s
1c960 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tmt;../*.** CAPI
1c970 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 3REF: Run-time L
1c980 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 imits.**.** ^(Th
1c990 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
1c9a0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
1c9b0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
1c9c0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
1c9d0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
1c9e0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
1c9f0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
1ca00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1ca10 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
1ca20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
1ca30 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
1ca40 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
1ca50 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
1ca60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
1ca70 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
1ca80 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
1ca90 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
1caa0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
1cab0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
1cac0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
1cad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1cae0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
1caf0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
1cb00 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t.)^.**.** ^If t
1cb10 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 he new limit is
1cb20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
1cb30 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 r, the limit is
1cb40 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 unchanged..** ^(
1cb50 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 For each limit c
1cb60 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c ategory SQLITE_L
1cb70 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e IMIT_<i>NAME</i>
1cb80 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
1cb90 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
1cba0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
1cbb0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
1cbc0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f me by a C prepro
1cbd0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c cessor macro cal
1cbe0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c led.** [limits |
1cbf0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e SQLITE_MAX_<i>N
1cc00 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 AME</i>]..** (Th
1cc10 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 e "_LIMIT_" in t
1cc20 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 he name is chang
1cc30 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 ed to "_MAX_".))
1cc40 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 ^.** ^Attempts t
1cc50 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d o increase a lim
1cc60 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 it above its har
1cc70 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 d upper bound ar
1cc80 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 e.** silently tr
1cc90 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 uncated to the h
1cca0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e ard upper bound.
1ccb0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 .**.** ^Regardle
1ccc0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
1ccd0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 not the limit w
1cce0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 as changed, the
1ccf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d .** [sqlite3_lim
1cd00 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 it()] interface
1cd10 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f returns the prio
1cd20 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c r value of the l
1cd30 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c imit..** ^Hence,
1cd40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 to find the cur
1cd50 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 rent value of a
1cd60 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 limit without ch
1cd70 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 anging it,.** si
1cd80 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 mply invoke this
1cd90 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 interface with
1cda0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
1cdb0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a ter set to -1..*
1cdc0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 *.** Run-time li
1cdd0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
1cde0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
1cdf0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
1ce00 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
1ce10 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
1ce20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
1ce30 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
1ce40 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
1ce50 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
1ce60 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
1ce70 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
1ce80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
1ce90 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f be a.** web bro
1cea0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
1ceb0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
1cec0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
1ced0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
1cee0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
1cef0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
1cf00 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
1cf10 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
1cf20 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
1cf30 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
1cf40 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
1cf50 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
1cf60 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
1cf70 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
1cf80 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
1cf90 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
1cfa0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
1cfb0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
1cfc0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
1cfd0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
1cfe0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
1cff0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
1d000 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
1d010 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
1d020 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1d030 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
1d040 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
1d050 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
1d060 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
1d070 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
1d080 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
1d090 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
1d0a0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
1d0b0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
1d0c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
1d0d0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
1d0e0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
1d0f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
1d100 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
1d110 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
1d120 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c */.int sqlite3_l
1d130 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
1d140 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
1d150 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1d160 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1d170 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
1d180 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
1d190 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
1d1a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
1d1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
1d1c0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
1d1d0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
1d1e0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
1d1f0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
1d200 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
1d210 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
1d220 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
1d230 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
1d240 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
1d250 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
1d260 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
1d270 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
1d280 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
1d290 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
1d2a0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
1d2b0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
1d2c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1d2d0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
1d2e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1d2f0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
1d300 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
1d310 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
1d320 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
1d330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
1d340 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
1d350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1d360 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1d370 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1d380 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
1d390 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1d3a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
1d3b0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e UMN</dt>.** <dd>
1d3c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1d3d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
1d3e0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 a table definit
1d3f0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a ion or in the.**
1d400 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
1d410 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 [SELECT] or the
1d420 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1d430 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e of columns in an
1d440 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 index.** or in
1d450 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 an ORDER BY or G
1d460 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c ROUP BY clause.<
1d470 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
1d480 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1d490 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
1d4a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d4b0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
1d4c0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
1d4d0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
1d4e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1d4f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
1d500 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
1d510 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1d520 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1d530 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
1d540 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
1d550 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
1d560 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
1d570 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 LIMIT_VDBE_OP</d
1d580 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1d590 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1d5a0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 instructions in
1d5b0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e a virtual machin
1d5c0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 e program.** use
1d5d0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
1d5e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
1d5f0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 This limit is
1d600 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a not currently.**
1d610 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 enforced, thoug
1d620 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 h that might be
1d630 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 added in some fu
1d640 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
1d650 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 ** SQLite.</dd>)
1d660 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
1d670 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
1d680 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
1d690 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1d6a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
1d6b0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
1d6c0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
1d6d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1d6e0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e IT_ATTACHED</dt>
1d6f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1d700 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 mum number of [A
1d710 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 TTACH | attached
1d720 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f databases].)^</
1d730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e dd>.**.** ^(<dt>
1d740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
1d750 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
1d760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1d770 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
1d780 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 of the pattern a
1d790 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
1d7a0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f LIKE] or.** [GLO
1d7b0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 B] operators.</d
1d7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1d7d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
1d7e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
1d7f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1d800 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 ximum index numb
1d810 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d er of any [param
1d820 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 eter] in an SQL
1d830 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a statement.)^.**.
1d840 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
1d850 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
1d860 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
1d870 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
1d880 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 h of recursion f
1d890 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 or triggers.</dd
1d8a0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a >)^.** </dl>.*/.
1d8b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1d8c0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
1d8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1d8e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d8f0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
1d900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d910 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
1d920 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
1d930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d940 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
1d950 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
1d960 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1d970 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
1d980 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1d990 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
1d9a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
1d9b0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
1d9c0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
1d9d0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
1d9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
1d9f0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
1da00 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
1da10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
1da20 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
1da30 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
1da40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
1da50 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
1da60 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
1da70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
1da80 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
1da90 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
1daa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
1dab0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
1dac0 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 10../*.*
1dad0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
1dae0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 iling An SQL Sta
1daf0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 tement.** KEYWOR
1db00 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 DS: {SQL stateme
1db10 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a nt compiler}.**.
1db20 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e ** To execute an
1db30 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d SQL query, it m
1db40 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d ust first be com
1db50 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 piled into a byt
1db60 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 e-code.** progra
1db70 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 m using one of t
1db80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
1db90 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
1dba0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 rgument, "db", i
1dbb0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
1dbc0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e nnection] obtain
1dbd0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 ed from a.** pri
1dbe0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
1dbf0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
1dc00 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1dc10 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a _open_v2()] or.*
1dc20 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
1dc30 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 6()]. The datab
1dc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d ase connection m
1dc50 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 ust not have bee
1dc60 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 n closed..**.**
1dc70 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
1dc80 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 ent, "zSql", is
1dc90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f the statement to
1dca0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e be compiled, en
1dcb0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 coded.** as eith
1dcc0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
1dcd0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 16. The sqlite3
1dce0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 _prepare() and s
1dcf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1dd00 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2().** interface
1dd10 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 s use UTF-8, and
1dd20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1dd30 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 16() and sqlite3
1dd40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a _prepare16_v2().
1dd50 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a ** use UTF-16..*
1dd60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 *.** ^If the nBy
1dd70 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c te argument is l
1dd80 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 ess than zero, t
1dd90 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 hen zSql is read
1dda0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 up to the.** fi
1ddb0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
1ddc0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 tor. ^If nByte i
1ddd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
1dde0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d then it is the m
1ddf0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 aximum.** number
1de00 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 of bytes read
1de10 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 from zSql. ^Whe
1de20 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e n nByte is non-n
1de30 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 egative, the.**
1de40 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 zSql string ends
1de50 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 at either the f
1de60 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 irst '\000' or '
1de70 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 \u0000' characte
1de80 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 r or.** the nByt
1de90 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 e-th byte, which
1dea0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
1deb0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 . If the caller
1dec0 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 knows.** that th
1ded0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e e supplied strin
1dee0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 g is nul-termina
1def0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 ted, then there
1df00 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 is a small.** pe
1df10 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 rformance advant
1df20 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 age to be gained
1df30 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e by passing an n
1df40 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 Byte parameter t
1df50 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 hat.** is equal
1df60 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 to the number of
1df70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e bytes in the in
1df80 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e put string <i>in
1df90 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 cluding</i>.** t
1dfa0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f he nul-terminato
1dfb0 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e r bytes..**.** ^
1dfc0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 If pzTail is not
1dfd0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 NULL then *pzTa
1dfe0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
1dff0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
1e000 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 byte.** past th
1e010 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 e end of the fir
1e020 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
1e030 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
1e040 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a routines only.*
1e050 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 * compile the fi
1e060 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e rst statement in
1e070 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
1e080 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
1e090 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 ng to.** what re
1e0a0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 mains uncompiled
1e0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 ..**.** ^*ppStmt
1e0c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
1e0d0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 g to a compiled
1e0e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1e0f0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 ent] that can be
1e100 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 .** executed usi
1e110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
1e120 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 ()]. ^If there
1e130 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
1e140 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
1e150 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 o NULL. ^If the
1e160 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
1e170 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 ains no SQL (if
1e180 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 the input is an
1e190 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 empty.** string
1e1a0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 or a comment) th
1e1b0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 en *ppStmt is se
1e1c0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 t to NULL..** Th
1e1d0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
1e1e0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
1e1f0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
1e200 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
1e210 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
1e220 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1e230 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
1e240 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
1e250 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d ith it..** ppStm
1e260 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c t may not be NUL
1e270 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 L..**.** ^On suc
1e280 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 cess, the sqlite
1e290 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 3_prepare() fami
1e2a0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 ly of routines r
1e2b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
1e2c0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 ];.** otherwise
1e2d0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
1e2e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1e2f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
1e300 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 repare_v2() and
1e310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1e320 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 6_v2() interface
1e330 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 s are.** recomme
1e340 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 nded for all new
1e350 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 programs. The t
1e360 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 wo older interfa
1e370 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 ces are retained
1e380 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 .** for backward
1e390 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
1e3a0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
1e3b0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
1e3c0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 * ^In the "v2" i
1e3d0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
1e3e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1e3f0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
1e400 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
1e410 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
1e420 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
1e430 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
1e440 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
1e450 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
1e460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1e470 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
1e480 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 behave different
1e490 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 ly in three ways
1e4a0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
1e4b0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
1e4c0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
1e4d0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
1e4e0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
1e4f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
1e500 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
1e510 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
1e520 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1e530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
1e540 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
1e550 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
1e560 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
1e570 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a gain..** </li>.*
1e580 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 *.** <li>.** ^Wh
1e590 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
1e5a0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
1e5b0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
1e5c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
1e5d0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
1e5e0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
1e5f0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
1e600 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 ^The legacy be
1e610 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a havior was that.
1e620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
1e630 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 ()] would only r
1e640 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 eturn a generic
1e650 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 [SQLITE_ERROR] r
1e660 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e esult code.** an
1e670 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
1e680 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 n would have to
1e690 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
1e6a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
1e6b0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 eset()].** in or
1e6c0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 der to find the
1e6d0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
1e6e0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
1e6f0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
1e700 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
1e710 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
1e720 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
1e730 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
1e740 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
1e750 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a y..** </li>.**.*
1e760 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
1e770 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
1e780 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d bound to [param
1e790 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 eter | host para
1e7a0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a meter] in the .*
1e7b0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d * WHERE clause m
1e7c0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
1e7d0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 he choice of que
1e7e0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 ry plan for a st
1e7f0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e atement,.** then
1e800 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
1e810 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
1e820 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c ally recompiled,
1e830 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 as if there had
1e840 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 been .** a sche
1e850 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 ma change, on th
1e860 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 e first [sqlite
1e870 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 3_step()] call f
1e880 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 ollowing any cha
1e890 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 nge.** to the [s
1e8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1e8b0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
1e8c0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d that [parameter]
1e8d0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 . .** ^The speci
1e8e0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 fic value of WHE
1e8f0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d RE-clause [param
1e900 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c eter] might infl
1e910 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 uence the .** ch
1e920 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
1e930 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 an if the parame
1e940 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d ter is the left-
1e950 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b hand side of a [
1e960 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f LIKE].** or [GLO
1e970 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 B] operator or i
1e980 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1e990 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 is compared to a
1e9a0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e n indexed column
1e9b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c .** and the [SQL
1e9c0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 ITE_ENABLE_STAT2
1e9d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1e9e0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
1e9f0 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c ..** the .** </l
1ea00 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 i>.** </ol>.*/.i
1ea10 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1ea20 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
1ea30 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1ea40 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1ea50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1ea60 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1ea70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1ea80 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
1ea90 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1eaa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1eab0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1eac0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1ead0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1eae0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1eaf0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1eb00 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1eb10 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
1eb20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1eb30 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1eb40 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1eb50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1eb60 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
1eb70 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1eb80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1eb90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1eba0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1ebb0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1ebc0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
1ebd0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1ebe0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1ebf0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1ec00 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1ec10 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1ec20 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1ec30 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1ec40 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1ec50 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
1ec60 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1ec70 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1ec80 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1ec90 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1eca0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
1ecb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1ecc0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1ecd0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1ece0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
1ecf0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1ed00 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
1ed10 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
1ed20 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1ed30 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1ed40 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1ed50 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1ed60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1ed70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1ed80 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1ed90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1eda0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1edb0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1edc0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1edd0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
1ede0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1edf0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
1ee00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1ee10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1ee20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1ee30 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1ee40 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1ee50 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1ee60 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1ee70 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1ee80 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1ee90 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1eea0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1eeb0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1eec0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1eed0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1eee0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1eef0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1ef00 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1ef10 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1ef20 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1ef30 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
1ef40 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
1ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
1ef60 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
1ef70 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 ed to retrieve a
1ef80 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 saved copy of t
1ef90 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 he original.** S
1efa0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 QL text used to
1efb0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 create a [prepar
1efc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 ed statement] if
1efd0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
1efe0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 was.** compiled
1eff0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
1f000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1f010 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1f020 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1f030 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1f040 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
1f050 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
1f060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1f070 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
1f080 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
1f090 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
1f0a0 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 base.**.** ^The
1f0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
1f0c0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 donly(X) interfa
1f0d0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
1f0e0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a (non-zero) if.**
1f0f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1f100 74 61 74 65 6d 65 6e 74 5d 20 58 20 69 73 20 5b tatement] X is [
1f110 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1f120 74 20 61 6e 64 20 66 61 6c 73 65 20 28 7a 65 72 t and false (zer
1f130 6f 29 20 69 66 0a 2a 2a 20 58 20 69 73 20 61 6e o) if.** X is an
1f140 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 [INSERT], [UPDA
1f150 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 43 TE], [DELETE], C
1f160 52 45 41 54 45 2c 20 44 52 4f 50 2c 20 5b 41 4e REATE, DROP, [AN
1f170 41 4c 59 5a 45 5d 2c 0a 2a 2a 20 5b 41 4c 54 45 ALYZE],.** [ALTE
1f180 52 5d 2c 20 6f 72 20 5b 52 45 49 4e 44 45 58 5d R], or [REINDEX]
1f190 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 49 statement..** I
1f1a0 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f X is a NULL po
1f1b0 69 6e 74 65 72 20 6f 72 20 61 6e 79 20 6f 74 68 inter or any oth
1f1c0 65 72 20 6b 69 6e 64 20 6f 66 20 73 74 61 74 65 er kind of state
1f1d0 6d 65 6e 74 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ment, including
1f1e0 62 75 74 0a 2a 2a 20 6e 6f 74 20 6c 69 6d 69 74 but.** not limit
1f1f0 65 64 20 74 6f 20 5b 41 54 54 41 43 48 5d 2c 20 ed to [ATTACH],
1f200 5b 44 45 54 41 43 48 5d 2c 20 5b 43 4f 4d 4d 49 [DETACH], [COMMI
1f210 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 20 T], [ROLLBACK],
1f220 5b 52 45 4c 45 41 53 45 5d 2c 0a 2a 2a 20 5b 53 [RELEASE],.** [S
1f230 41 56 45 50 4f 49 4e 54 5d 2c 20 5b 50 52 41 47 AVEPOINT], [PRAG
1f240 4d 41 5d 2c 20 6f 72 20 5b 56 41 43 55 55 4d 5d MA], or [VACUUM]
1f250 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 73 the result of s
1f260 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
1f270 6f 6e 6c 79 28 58 29 20 69 73 0a 2a 2a 20 75 6e only(X) is.** un
1f280 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 defined..*/.int
1f290 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
1f2a0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 donly(sqlite3_st
1f2b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
1f2c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
1f2d0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
1f2e0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
1f2f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
1f300 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1f310 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
1f320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
1f330 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
1f340 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
1f350 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
1f360 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
1f370 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
1f380 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
1f390 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
1f3a0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
1f3b0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
1f3c0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
1f3d0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
1f3e0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
1f3f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
1f400 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
1f410 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
1f420 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
1f430 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
1f440 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
1f450 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1f460 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
1f470 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
1f480 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
1f490 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
1f4a0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
1f4b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1f4c0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
1f4d0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
1f4e0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
1f4f0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
1f500 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1f510 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
1f520 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
1f530 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
1f540 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
1f550 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
1f560 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
1f570 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
1f580 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1f590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
1f5a0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
1f5b0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
1f5c0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
1f5d0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
1f5e0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
1f5f0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
1f600 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
1f610 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1f620 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
1f630 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
1f640 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
1f650 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1f660 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
1f670 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1f680 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
1f690 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
1f6a0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
1f6b0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
1f6c0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
1f6d0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
1f6e0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
1f6f0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
1f700 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
1f710 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
1f720 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1f730 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
1f740 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1f750 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
1f760 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
1f770 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
1f780 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
1f790 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
1f7a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1f7b0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
1f7c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
1f7d0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
1f7e0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
1f7f0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
1f800 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
1f810 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
1f820 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
1f830 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
1f840 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
1f850 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
1f860 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
1f870 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1f880 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
1f890 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
1f8a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
1f8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1f8c0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
1f8d0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
1f8e0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
1f8f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1f900 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
1f910 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1f920 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
1f930 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
1f940 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1f950 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
1f960 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
1f970 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
1f980 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
1f990 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1f9a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
1f9b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
1f9c0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
1f9d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
1f9e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
1f9f0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
1fa00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
1fa10 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
1fa20 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
1fa30 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
1fa40 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
1fa50 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
1fa60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1fa70 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
1fa80 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
1fa90 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
1faa0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
1fab0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
1fac0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
1fad0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
1fae0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
1faf0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
1fb00 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
1fb10 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
1fb20 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
1fb30 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
1fb40 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
1fb50 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
1fb60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
1fb70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
1fb80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
1fb90 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1fba0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1fbb0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
1fbc0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
1fbd0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
1fbe0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
1fbf0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1fc00 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
1fc10 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
1fc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
1fc30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
1fc40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
1fc50 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
1fc60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
1fc70 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
1fc80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
1fc90 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
1fca0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
1fcb0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
1fcc0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1fcd0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
1fce0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
1fcf0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
1fd00 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
1fd10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
1fd20 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
1fd30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
1fd40 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
1fd50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
1fd60 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
1fd70 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
1fd80 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
1fd90 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
1fda0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 binding}.**.**
1fdb0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 ^(In the SQL sta
1fdc0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 tement text inpu
1fdd0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
1fde0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1fdf0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
1fe00 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
1fe10 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b replaced by a [
1fe20 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 parameter] that
1fe30 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 matches one of f
1fe40 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 ollowing.** temp
1fe50 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c lates:.**.** <ul
1fe60 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 >.** <li> ?.**
1fe70 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c <li> ?NNN.** <l
1fe80 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> :VVV.** <li>
1fe90 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 @VVV.** <li>
1fea0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a $VVV.** </ul>.**
1feb0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c .** In the templ
1fec0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 ates above, NNN
1fed0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e represents an in
1fee0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a teger literal,.*
1fef0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 * and VVV repres
1ff00 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d ents an alphanum
1ff10 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e eric identifier.
1ff20 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 )^ ^The values
1ff30 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1ff40 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1ff50 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1ff60 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1ff70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1ff80 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1ff90 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1ffa0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1ffb0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1ffc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1ffd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1ffe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1fff0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
20000 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
20010 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
20020 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
20030 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
20040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20050 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
20060 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 riants..**.** ^T
20070 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
20080 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
20090 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
200a0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
200b0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 ** ^The leftmost
200c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
200d0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
200e0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d . ^When the sam
200f0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
20100 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
20110 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
20120 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
20130 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
20140 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
20150 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
20160 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
20170 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 e..** ^The index
20180 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
20190 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
201a0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
201b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
201c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
201d0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
201e0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 red. ^The index
201f0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
20200 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
20210 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
20220 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 * ^The NNN value
20230 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
20240 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 1 and the [sqli
20250 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
20260 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 parameter [SQLIT
20270 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
20280 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c _NUMBER] (defaul
20290 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a t value: 999)..*
202a0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
202b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
202c0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
202d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
202e0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
202f0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
20300 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
20310 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
20320 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
20330 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
20340 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
20350 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
20360 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
20370 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
20380 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
20390 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
203a0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
203b0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
203c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
203d0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
203e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
203f0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
20400 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
20410 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
20420 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
20430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
20440 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
20450 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
20460 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
20470 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
20480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
20490 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
204a0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
204b0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
204c0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
204d0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
204e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
204f0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
20500 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 r is called.** t
20510 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
20520 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
20530 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c even if the call
20540 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
20550 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 _blob(),.** sqli
20560 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c te3_bind_text(),
20570 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
20580 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e _text16() fails.
20590 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 .** ^If the fi
205a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
205b0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
205c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
205d0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
205e0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
205f0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
20600 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
20610 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
20620 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
20630 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
20640 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
20650 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
20660 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
20670 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
20680 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
20690 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
206a0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
206b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
206c0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
206d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
206e0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
206f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
20700 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
20710 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
20720 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
20730 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
20740 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
20750 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
20760 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
20770 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
20780 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
20790 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
207a0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
207b0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
207c0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
207d0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
207e0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
207f0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
20800 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
20810 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
20820 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
20830 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
20840 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
20850 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
20860 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
20870 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
20880 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
20890 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
208a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
208b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
208c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
208d0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
208e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
208f0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
20900 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
20910 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
20920 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
20930 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
20940 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
20950 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
20960 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
20970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
20980 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
20990 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
209a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
209b0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
209c0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
209d0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
209e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
209f0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
20a00 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
20a10 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
20a20 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
20a30 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
20a40 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
20a50 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
20a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
20a70 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
20a80 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
20a90 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
20aa0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
20ab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
20ac0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
20ad0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
20ae0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
20af0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
20b00 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
20b10 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
20b20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 ^[SQLITE_RANGE]
20b30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
20b40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
20b50 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
20b60 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 range. ^[SQLITE
20b70 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
20b80 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
20b90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fails..**.** See
20ba0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
20bb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
20bc0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
20bd0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
20be0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
20bf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
20c00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
20c10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
20c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
20c30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
20c40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
20c50 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
20c60 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
20c70 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
20c80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
20c90 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
20ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
20cb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
20cc0 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
20cd0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
20ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
20cf0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
20d00 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
20d10 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
20d20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
20d30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
20d40 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
20d50 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
20d60 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
20d70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
20d80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
20d90 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
20da0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
20db0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
20dc0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
20dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
20de0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
20df0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
20e00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
20e10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
20e20 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
20e30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
20e40 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
20e50 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
20e60 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
20e70 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
20e80 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ne can be used t
20e90 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
20ea0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 r of [SQL parame
20eb0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 ters].** in a [p
20ec0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20ed0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 t]. SQL paramet
20ee0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f ers are tokens o
20ef0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f f the.** form "?
20f00 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 ", "?NNN", ":AAA
20f10 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 ", "$AAA", or "@
20f20 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 AAA" that serve
20f30 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 as.** placeholde
20f40 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 rs for values th
20f50 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f at are [sqlite3_
20f60 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e bind_blob | boun
20f70 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 d].** to the par
20f80 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 ameters at a lat
20f90 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e er time..**.** ^
20fa0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 (This routine ac
20fb0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
20fc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
20fd0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
20fe0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
20ff0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
21000 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
21010 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
21020 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
21030 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
21040 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
21050 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
21060 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 NNN form are use
21070 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 d,.** there may
21080 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c be gaps in the l
21090 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 ist.)^.**.** See
210a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
210b0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
210c0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
210d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
210e0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
210f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
21100 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
21110 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
21120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
21130 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
21140 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
21150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
21160 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
21170 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 meter.**.** ^The
21180 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
21190 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
211a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
211b0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
211c0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
211d0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
211e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
211f0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
21200 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
21210 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
21220 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
21230 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
21240 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
21250 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
21260 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
21270 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
21280 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
21290 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
212a0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
212b0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
212c0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
212d0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
212e0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
212f0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
21300 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
21310 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
21320 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
21330 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
21340 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
21350 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
21360 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
21370 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
21380 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
21390 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
213a0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
213b0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
213c0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
213d0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
213e0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
213f0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
21400 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
21410 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
21420 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
21430 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
21440 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
21450 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
21460 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
21470 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
21480 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
21490 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
214a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
214b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
214c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
214d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
214e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
214f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
21500 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
21510 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
21520 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
21530 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
21540 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
21550 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
21560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
21570 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
21580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
21590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
215a0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
215b0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
215c0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e ven Name.**.** ^
215d0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
215e0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
215f0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
21600 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e ame. ^The.** in
21610 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e dex value return
21620 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 ed is suitable f
21630 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 or use as the se
21640 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 cond.** paramete
21650 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 r to [sqlite3_bi
21660 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
21670 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 bind()]. ^A zer
21680 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
21690 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
216a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
216b0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 nd. ^The parame
216c0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 ter.** name must
216d0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 be given in UTF
216e0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f -8 even if the o
216f0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
21700 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 t.** was prepare
21710 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 d from UTF-16 te
21720 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 xt using [sqlite
21730 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
21740 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
21750 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
21760 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
21770 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
21780 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
21790 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
217a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
217b0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
217c0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
217d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
217e0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
217f0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
21800 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
21810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
21820 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
21830 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
21840 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 atement.**.** ^C
21850 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
21860 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
21870 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
21880 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
21890 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
218a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
218b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
218c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
218d0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
218e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
218f0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
21900 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
21910 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
21920 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
21930 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
21940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
21950 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
21960 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
21970 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
21980 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
21990 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
219a0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
219b0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
219c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
219d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
219e0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 urns 0 if pStmt
219f0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 is an SQL.** sta
21a00 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 tement that does
21a10 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 not return data
21a20 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e (for example an
21a30 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a [UPDATE])..**.*
21a40 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
21a50 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
21a60 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )].*/.int sqlite
21a70 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
21a80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
21a90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
21aa0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
21ab0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
21ac0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 et.**.** ^These
21ad0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
21ae0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
21af0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
21b00 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
21b10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
21b20 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
21b30 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
21b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
21b50 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
21b60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
21b70 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
21b80 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
21b90 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
21ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
21bb0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
21bc0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
21bd0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
21be0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
21bf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
21c00 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
21c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
21c20 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
21c30 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
21c40 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
21c50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
21c60 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
21c70 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
21c80 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
21c90 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
21ca0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
21cb0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
21cc0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
21cd0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
21ce0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
21cf0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
21d00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
21d10 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
21d20 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a e next call to.*
21d30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
21d40 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 _name() or sqlit
21d50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
21d60 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 () on the same c
21d70 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 olumn..**.** ^If
21d80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21d90 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 ) fails during t
21da0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 he processing of
21db0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a either routine.
21dc0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ** (for example
21dd0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 during a convers
21de0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 ion from UTF-8 t
21df0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 o UTF-16) then a
21e00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
21e10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
21e20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
21e30 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
21e40 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
21e50 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
21e60 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
21e70 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
21e80 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
21e90 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
21ea0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
21eb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
21ec0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
21ed0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
21ee0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
21ef0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
21f00 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
21f10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
21f20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
21f30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
21f40 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 *, int N);.const
21f50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
21f60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
21f70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
21f80 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
21f90 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
21fa0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
21fb0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 esult.**.** ^The
21fc0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
21fd0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
21fe0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 etermine the dat
21ff0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
22000 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d d.** table colum
22010 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 n that is the or
22020 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 igin of a partic
22030 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 ular result colu
22040 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 mn in.** [SELECT
22050 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
22060 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
22070 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
22080 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
22090 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
220a0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
220b0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
220c0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 ng. ^The _datab
220d0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ase_ routines re
220e0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 turn.** the data
220f0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f base name, the _
22100 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 table_ routines
22110 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 return the table
22120 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 name, and.** th
22130 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e e origin_ routin
22140 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f es return the co
22150 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 lumn name..** ^T
22160 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
22170 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
22180 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
22190 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
221a0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
221b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
221c0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
221d0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
221e0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
221f0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
22200 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
22210 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 g..**.** ^The na
22220 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
22230 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
22240 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
22250 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
22260 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
22270 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lumn..**.** ^The
22280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
22290 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
222a0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 ces is a [prepar
222b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
222c0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
222d0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
222e0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
222f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
22300 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
22310 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
22320 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
22330 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
22340 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
22350 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d left-most colum
22360 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f n is column 0 fo
22370 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
22380 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
22390 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
223a0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
223b0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
223c0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
223d0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
223e0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
223f0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
22400 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
22410 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 rn.** NULL. ^Th
22420 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
22430 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
22440 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
22450 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
22460 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 ** occurs. ^Oth
22470 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
22480 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
22490 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
224a0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a abase, table,.**
224b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 or column that
224c0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
224d0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
224e0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 d from..**.** ^A
224f0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
22500 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
22510 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 ose whose names
22520 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 end with "16" re
22530 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
22540 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 ncoded strings a
22550 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e nd the other fun
22560 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
22570 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 F-8..**.** ^Thes
22580 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 e APIs are only
22590 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
225a0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
225b0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
225c0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
225d0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
225e0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
225f0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 symbol..**.** I
22600 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
22610 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
22620 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
22630 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
22640 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
22650 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
22660 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
22670 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
22680 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
22690 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
226a0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
226b0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
226c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
226d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
226e0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
226f0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
22700 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
22710 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
22720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22730 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
22740 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
22750 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
22760 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
22770 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
22780 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
22790 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
227a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
227b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
227c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
227d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
227e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
227f0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
22800 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
22810 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
22820 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
22830 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
22840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
22850 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
22860 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
22870 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
22880 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
22890 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
228a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
228b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
228c0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
228d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
228e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
228f0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
22900 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
22910 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
22920 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
22930 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
22940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
22950 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
22960 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
22970 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
22980 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
22990 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
229a0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
229b0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
229c0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
229d0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
229e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
229f0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
22a00 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
22a10 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
22a20 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
22a30 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
22a40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
22a50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
22a60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
22a70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
22a80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
22a90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
22aa0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
22ab0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
22ac0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
22ad0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
22ae0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
22af0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
22b00 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
22b10 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
22b20 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
22b30 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
22b40 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
22b50 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
22b60 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
22b70 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
22b80 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
22b90 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
22ba0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
22bb0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
22bc0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
22bd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
22be0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
22bf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
22c00 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
22c10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
22c20 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
22c30 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
22c40 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
22c50 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
22c60 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
22c70 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
22c80 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
22c90 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
22ca0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
22cb0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
22cc0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
22cd0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
22ce0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
22cf0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
22d00 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
22d10 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
22d20 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
22d30 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
22d40 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
22d50 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
22d60 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
22d70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
22d80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
22d90 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
22da0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
22db0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
22dc0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
22dd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
22de0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
22df0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
22e00 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
22e10 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
22e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22e30 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
22e40 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
22e50 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
22e60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
22e70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22e80 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
22e90 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
22ea0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
22eb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
22ec0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
22ed0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
22ee0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
22ef0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
22f00 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
22f10 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
22f20 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
22f30 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
22f40 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
22f50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
22f60 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
22f70 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
22f80 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
22f90 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
22fa0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
22fb0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
22fc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
22fd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
22fe0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
22ff0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
23000 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
23010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
23020 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
23030 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
23040 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
23050 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
23060 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
23070 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
23080 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
23090 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
230a0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
230b0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
230c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
230d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
230e0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
230f0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
23100 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
23110 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
23120 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
23130 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
23140 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
23150 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
23160 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
23170 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
23180 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
23190 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
231a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
231b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
231c0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
231d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
231e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
231f0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
23200 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
23210 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
23220 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
23230 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
23240 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
23250 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
23260 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
23270 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
23280 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
23290 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
232a0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
232b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
232c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
232d0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
232e0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
232f0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 n a.** explicit
23300 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
23310 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
23320 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
23330 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
23340 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
23350 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 ^[SQLITE_DONE]
23360 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
23370 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
23380 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
23390 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
233a0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
233b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
233c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
233d0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
233e0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
233f0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
23400 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
23410 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
23420 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
23430 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
23440 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
23450 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 ^If the SQL stat
23460 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 ement being exec
23470 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 uted returns any
23480 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c data, then [SQL
23490 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 ITE_ROW].** is r
234a0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
234b0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
234c0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 ata is ready for
234d0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 processing by t
234e0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 he.** caller. Th
234f0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
23500 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 accessed using t
23510 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 he [column acces
23520 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a s functions]..**
23530 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
23540 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 is called again
23550 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 to retrieve the
23560 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 next row of data
23570 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
23580 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
23590 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
235a0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
235b0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
235c0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
235d0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
235e0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
235f0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
23600 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
23610 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
23620 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
23630 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
23640 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e _errmsg()]..** ^
23650 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
23660 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
23670 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
23680 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
23690 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
236a0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
236b0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
236c0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
236d0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
236e0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
236f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
23700 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
23710 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
23720 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e statement]. ^In
23730 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
23740 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
23750 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
23760 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
23770 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
23780 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
23790 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
237a0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
237b0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
237c0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
237d0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
237e0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
237f0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 led on a [prepar
23800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
23810 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 at has.** alread
23820 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f y been [sqlite3_
23830 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
23840 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 ized] or on one
23850 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 that had.** prev
23860 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 iously returned
23870 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f [SQLITE_ERROR] o
23880 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
23890 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a Or it could.**
238a0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
238b0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 t the same datab
238c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
238d0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 s being used by
238e0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 two or.** more t
238f0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 hreads at the sa
23900 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d me moment in tim
23910 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c e..**.** For all
23920 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
23930 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e ite up to and in
23940 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 cluding 3.6.23.1
23950 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65 , it was require
23960 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 d.** after sqlit
23970 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e e3_step() return
23980 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 ed anything othe
23990 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
239a0 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c OW] that.** [sql
239b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 ite3_reset()] be
239c0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 called before a
239d0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
239e0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
239f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
23a00 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b Failure to invok
23a10 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
23a20 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 ()] in this way
23a30 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 would.** result
23a40 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 in an [SQLITE_MI
23a50 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f SUSE] return fro
23a60 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 m sqlite3_step()
23a70 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 . But after.**
23a80 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 version 3.6.23.1
23a90 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
23aa0 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b began calling [
23ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
23ac0 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c .** automatical
23ad0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 ly in this circu
23ae0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 mstance rather t
23af0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
23b00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
23b10 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
23b20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
23b30 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
23b40 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
23b50 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
23b60 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
23b70 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
23b80 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
23b90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
23ba0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
23bb0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
23bc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
23bd0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
23be0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
23bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
23c00 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
23c10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
23c20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
23c30 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
23c40 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
23c50 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
23c60 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
23c70 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
23c80 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
23c90 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
23ca0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
23cb0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
23cc0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
23cd0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
23ce0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
23cf0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
23d00 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
23d10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
23d20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
23d30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
23d40 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
23d50 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
23d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
23d70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
23d80 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
23d90 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
23da0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
23db0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
23dc0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
23dd0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
23de0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
23df0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
23e00 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
23e10 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 ommended..*/.int
23e20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
23e30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
23e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
23e50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
23e60 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
23e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
23e80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
23e90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
23ea0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
23eb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
23ec0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 .** current row
23ed0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
23ee0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 t of [prepared s
23ef0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
23f00 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 ^If prepared sta
23f10 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f tement P does no
23f20 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 t have results r
23f30 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a eady to return.*
23f40 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 * (via calls to
23f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
23f60 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 umn_int | sqlite
23f70 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 3_column_*()] of
23f80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 .** interfaces)
23f90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 then sqlite3_dat
23fa0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 a_count(P) retur
23fb0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ns 0..** ^The sq
23fc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
23fd0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f (P) routine also
23fe0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 returns 0 if P
23ff0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
24000 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 r..**.** See als
24010 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 o: [sqlite3_colu
24020 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 mn_count()].*/.i
24030 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f nt sqlite3_data_
24040 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
24050 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
24060 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
24070 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 damental Datatyp
24080 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
24090 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
240a0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 * ^(Every value
240b0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
240c0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
240d0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
240e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
240f0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
24100 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
24110 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
24120 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
24130 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
24140 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
24150 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
24160 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
24170 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
24180 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
24190 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
241a0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
241b0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
241c0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
241d0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
241e0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
241f0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
24200 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
24210 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
24220 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
24230 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
24240 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
24250 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
24260 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
24270 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
24280 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
24290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
242a0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
242b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
242c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
242d0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
242e0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
242f0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
24300 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
24310 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
24320 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
24330 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
24340 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
24350 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
24360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
24370 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
24380 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b rom A Query.** K
24390 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
243a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
243b0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
243c0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
243d0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e "result set" in
243e0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
243f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
24400 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
24410 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
24420 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
24430 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
24440 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
24450 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
24460 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
24470 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
24480 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
24490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
244a0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
244b0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
244c0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
244d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
244e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
244f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
24500 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
24510 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
24520 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
24530 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
24540 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
24550 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
24560 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
24570 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
24580 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
24590 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
245a0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
245b0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
245c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
245d0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
245e0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
245f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
24600 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
24610 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
24620 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
24630 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
24640 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
24650 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
24660 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
24670 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
24680 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
24690 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
246a0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
246b0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
246c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
246d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
246e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
246f0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
24700 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
24710 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
24720 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
24730 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
24740 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
24750 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
24760 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
24770 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
24780 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
24790 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
247a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
247b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
247c0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
247d0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
247e0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
247f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
24800 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
24810 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
24820 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
24830 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
24840 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
24850 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
24860 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
24870 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
24880 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
24890 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
248a0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
248b0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
248c0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
248d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
248e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
248f0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
24900 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
24910 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
24920 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
24930 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
24940 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
24950 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
24960 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
24970 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
24980 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
24990 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
249a0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
249b0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
249c0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
249d0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
249e0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
249f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
24a00 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
24a10 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
24a20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
24a30 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
24a40 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
24a50 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
24a60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
24a70 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
24a80 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
24a90 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
24aa0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
24ab0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
24ac0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
24ad0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
24ae0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
24af0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
24b00 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
24b10 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
24b20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
24b30 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
24b40 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
24b50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
24b60 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
24b70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
24b80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
24b90 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
24ba0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
24bb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
24bc0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
24bd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
24be0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
24bf0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
24c00 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
24c10 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
24c20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
24c30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
24c40 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
24c50 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
24c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
24c70 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
24c80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
24c90 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
24ca0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
24cb0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
24cc0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
24cd0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
24ce0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
24cf0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
24d00 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
24d10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
24d20 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
24d30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
24d40 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
24d50 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
24d60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
24d70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
24d80 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
24d90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
24da0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
24db0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
24dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
24dd0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
24de0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
24df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
24e00 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
24e10 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
24e20 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
24e30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
24e40 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
24e50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
24e60 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
24e70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
24e80 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
24e90 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
24ea0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
24eb0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
24ec0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
24ed0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
24ee0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
24ef0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
24f00 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
24f10 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
24f20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
24f30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
24f40 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
24f50 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
24f60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
24f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
24f80 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
24f90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
24fa0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
24fb0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
24fc0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
24fd0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
24fe0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
24ff0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
25000 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
25010 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
25020 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
25030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
25040 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
25050 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
25060 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
25070 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
25080 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
25090 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
250a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
250b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
250c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
250d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
250e0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
250f0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
25100 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 s zero terminate
25110 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
25120 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
25130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
25140 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
25150 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
25160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
25170 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 .** ^The object
25180 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
25190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
251a0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
251b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
251c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
251d0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
251e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
251f0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
25200 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
25210 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
25220 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
25230 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
25240 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
25250 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
25260 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
25270 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
25280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
25290 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
252a0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
252b0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
252c0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
252d0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
252e0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
252f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
25300 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
25310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
25320 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
25330 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
25340 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
25350 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
25360 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
25370 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
25380 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 propriate. ^For
25390 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
253a0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
253b0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
253c0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
253d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
253e0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
253f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
25400 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
25410 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
25420 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
25430 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 omatically. ^(T
25440 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 he following tab
25450 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 le details the c
25460 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 onversions.** th
25470 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a at are applied:.
25480 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
25490 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
254a0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
254b0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 <th> Internal<br
254c0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 >Type <th> Reque
254d0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 sted<br>Type <th
254e0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a > Conversion.**
254f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
25500 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
25510 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
25520 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
25530 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
25540 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
25550 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
25560 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
25570 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
25580 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
25590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
255a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
255b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
255c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
255d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
255e0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
255f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
25600 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
25610 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
25620 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
25630 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
25640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
25650 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
25660 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
25670 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
25680 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
25690 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
256a0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
256b0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
256c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
256d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
256e0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 float to intege
256f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 r.** <tr><td> F
25700 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
25710 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
25720 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
25730 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
25740 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
25750 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
25760 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e Same as FLOAT->
25770 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
25780 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 TEXT <td> I
25790 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 NTEGER <td> Us
257a0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
257b0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
257c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
257d0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 > Use atof().**
257e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
257f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
25800 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a <td> No change.
25810 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
25820 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 B <td> INTEGE
25830 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
25840 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 to TEXT then us
25850 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
25860 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
25870 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
25880 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
25890 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 T then use atof(
258a0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
258b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 LOB <td> TE
258c0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 XT <td> Add a
258d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
258e0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f if needed.** </
258f0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
25900 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
25910 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
25920 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
25930 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
25940 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
25950 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
25960 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
25970 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
25980 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
25990 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
259a0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
259b0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
259c0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
259d0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
259e0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
259f0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
25a00 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
25a10 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
25a20 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
25a30 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
25a40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
25a50 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
25a60 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
25a70 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
25a80 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
25a90 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
25aa0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
25ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
25ac0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
25ad0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
25ae0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
25af0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
25b00 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
25b10 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
25b20 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
25b30 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
25b40 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
25b50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
25b60 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
25b70 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
25b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
25b90 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
25ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
25bb0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
25bc0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
25bd0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
25be0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
25bf0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
25c00 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
25c10 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
25c20 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
25c30 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
25c40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
25c50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
25c60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
25c70 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
25c80 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
25c90 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
25ca0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
25cb0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
25cc0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
25cd0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
25ce0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
25cf0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
25d00 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
25d10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
25d20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
25d30 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
25d40 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
25d50 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
25d60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f </ul>.**.** ^Co
25d70 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
25d80 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
25d90 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
25da0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
25db0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
25dc0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
25dd0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
25de0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
25df0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
25e00 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
25e10 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
25e20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 references will
25e30 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
25e40 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
25e50 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
25e60 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
25e70 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
25e80 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
25e90 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
25ea0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
25eb0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
25ec0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
25ed0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
25ee0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 d..**.** The saf
25ef0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 est and easiest
25f00 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 to remember poli
25f10 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 cy is to invoke
25f20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
25f30 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 * in one of the
25f40 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a following ways:.
25f50 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c **.** <ul>.** <
25f60 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
25f70 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 n_text() followe
25f80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
25f90 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
25fa0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
25fb0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
25fc0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
25fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
25fe0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
25ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
26000 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 xt16() followed
26010 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
26020 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e n_bytes16()</li>
26030 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
26040 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
26050 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 you should call
26060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
26070 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 ext(),.** sqlite
26080 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
26090 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
260a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 mn_text16() firs
260b0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 t to force the r
260c0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 esult.** into th
260d0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 e desired format
260e0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 , then invoke sq
260f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
26100 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 es() or.** sqlit
26110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
26120 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6() to find the
26130 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 size of the resu
26140 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 lt. Do not mix
26150 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 calls.** to sqli
26160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
26170 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
26180 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 umn_blob() with
26190 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
261a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
261b0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 16(), and do not
261c0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 mix calls to sq
261d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
261e0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 t16().** with ca
261f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
26200 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a olumn_bytes()..*
26210 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 *.** ^The pointe
26220 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 rs returned are
26230 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 valid until a ty
26240 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 pe conversion oc
26250 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 curs as.** descr
26260 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 ibed above, or u
26270 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ntil [sqlite3_st
26280 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
26290 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
262a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
262b0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e ze()] is called.
262c0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 ^The memory sp
262d0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 ace used to hold
262e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 strings.** and
262f0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 BLOBs is freed a
26300 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 utomatically. D
26310 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 o <b>not</b> pas
26320 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 s the pointers r
26330 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 eturned.** [sqli
26340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
26350 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c )], [sqlite3_col
26360 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 umn_text()], etc
26370 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 . into.** [sqlit
26380 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
26390 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 * ^(If a memory
263a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
263b0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
263c0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
263d0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 any.** of these
263e0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 routines, a def
263f0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 ault value is re
26400 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 turned. The def
26410 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 ault value.** is
26420 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 either the inte
26430 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 ger 0, the float
26440 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
26450 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 0.0, or a NULL.
26460 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 ** pointer. Sub
26470 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
26480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
26490 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e e()] will return
264a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
264b0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 M].)^.*/.const v
264c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
264d0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 umn_blob(sqlite3
264e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
264f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
26500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
26510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
26520 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
26530 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
26540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
26550 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c int iCol);.doubl
26560 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
26570 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
26580 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
26590 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
265a0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 lumn_int(sqlite3
265b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
265c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
265d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
265e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
265f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
26600 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
26610 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
26620 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
26630 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
26640 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
26650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
26660 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
26670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
26680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
26690 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 n_type(sqlite3_s
266a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
266b0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a .sqlite3_value *
266c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
266d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
266e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
266f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26700 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
26710 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
26720 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ect.**.** ^The s
26730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
26740 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
26750 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
26760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26770 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 ment]..** ^If th
26780 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
26790 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 aluation of the
267a0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e statement encoun
267b0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 tered no errors
267c0 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 or.** or if the
267d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 statement is nev
267e0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 er been evaluate
267f0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f d, then sqlite3_
26800 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 finalize() retur
26810 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e ns.** SQLITE_OK.
26820 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ^If the most r
26830 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ecent evaluation
26840 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 of statement S
26850 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 failed, then.**
26860 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
26870 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 (S) returns the
26880 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
26890 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b or code] or.** [
268a0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
268b0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
268c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
268d0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e e(S) routine can
268e0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
268f0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a y point during.*
26900 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 * the life cycle
26910 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
26920 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 atement] S:.** b
26930 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 efore statement
26940 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 S is ever evalua
26950 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e ted, after.** on
26960 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 e or more calls
26970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
26980 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 t()], or after a
26990 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 ny call.** to [s
269a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
269b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
269c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
269d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a statement has.**
269e0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 completed execu
269f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 tion..**.** ^Inv
26a00 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 oking sqlite3_fi
26a10 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 nalize() on a NU
26a20 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 LL pointer is a
26a30 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
26a40 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
26a50 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c ation must final
26a60 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 ize every [prepa
26a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
26a80 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 n order to avoid
26a90 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 .** resource lea
26aa0 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 ks. It is a gri
26ab0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 evous error for
26ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
26ad0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a to try to use.**
26ae0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
26af0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
26b00 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
26b10 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 d. Any use of a
26b20 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
26b30 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
26b40 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
26b50 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e ed can result in
26b60 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a undefined and.*
26b70 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 * undesirable be
26b80 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 havior such as s
26b90 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 egfaults and hea
26ba0 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f p corruption..*/
26bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e .int sqlite3_fin
26bc0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
26bd0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
26be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
26bf0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
26c00 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
26c10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
26c20 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
26c30 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
26c40 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
26c50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
26c60 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
26c70 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
26c80 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
26c90 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e executed..** ^An
26ca0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
26cb0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
26cc0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
26cd0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
26ce0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
26cf0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
26d00 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
26d10 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
26d20 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
26d30 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
26d40 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
26d50 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
26d60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
26d70 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
26d80 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
26d90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26da0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 ment] S.** back
26db0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
26dc0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
26dd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
26de0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
26df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
26e00 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
26e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26e20 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 ent] S returned
26e30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
26e40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a [SQLITE_DONE],.*
26e50 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 * or if [sqlite3
26e60 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
26e70 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
26e80 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
26e90 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 then [sqlite3_re
26ea0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
26eb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
26ec0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
26ed0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
26ee0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
26ef0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
26f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
26f10 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
26f20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b error, then.** [
26f30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
26f40 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 ] returns an app
26f50 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
26f60 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
26f70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
26f80 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
26f90 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
26fa0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 he values.** of
26fb0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e any [sqlite3_bin
26fc0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d d_blob|bindings]
26fd0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 on the [prepare
26fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
26ff0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
27000 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
27010 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
27020 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
27030 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
27040 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 QL Functions.**
27050 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
27060 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
27070 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
27080 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
27090 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
270a0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
270b0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
270c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
270d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 ctions}.**.** ^T
270e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 hese functions (
270f0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f collectively kno
27100 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 wn as "function
27110 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
27120 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 s").** are used
27130 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
27140 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
27150 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e es or to redefin
27160 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a e the behavior.*
27170 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 * of existing SQ
27180 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
27190 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 ggregates. The
271a0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 only differences
271b0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 between.** thes
271c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 e routines are t
271d0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
271e0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a expected for.**
271f0 20 74 68 65 20 74 68 65 20 73 65 63 6f 6e 64 20 the the second
27200 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e parameter (the n
27210 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 ame of the funct
27220 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 ion being create
27230 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 d).** and the pr
27240 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 esence or absenc
27250 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f e of a destructo
27260 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a r callback for.*
27270 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
27280 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a n data pointer..
27290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
272a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
272b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
272c0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 ection] to which
272d0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
272e0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 tion is to be ad
272f0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 ded. ^If an app
27300 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f lication uses mo
27310 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 re than one data
27320 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
27330 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 on then applicat
27340 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
27350 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
27360 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 e added.** to ea
27370 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
27380 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c ection separatel
27390 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 y..**.** ^The se
273a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
273b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
273c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
273d0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a o be created or.
273e0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e ** redefined. ^
273f0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
27400 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
27410 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 d to 255 bytes i
27420 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 n a UTF-8.** rep
27430 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 resentation, exc
27440 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 lusive of the ze
27450 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro-terminator.
27460 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e ^Note that the n
27470 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 ame.** length li
27480 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 mit is in UTF-8
27490 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 bytes, not chara
274a0 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 cters nor UTF-16
274b0 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e bytes. .** ^An
274c0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 y attempt to cre
274d0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 ate a function w
274e0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d ith a longer nam
274f0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 e.** will result
27500 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 in [SQLITE_MISU
27510 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e SE] being return
27520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 ed..**.** ^The t
27530 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 hird parameter (
27540 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 nArg).** is the
27550 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
27560 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c nts that the SQL
27570 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
27580 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e aggregate takes.
27590 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 ^If this parame
275a0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 ter is -1, then
275b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
275c0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
275d0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
275e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
275f0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 s between 0 and
27600 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 the limit.** set
27610 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
27620 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
27630 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 T_FUNCTION_ARG])
27640 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a . If the third.
27650 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ** parameter is
27660 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 less than -1 or
27670 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 greater than 127
27680 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
27690 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e or is.** undefin
276a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
276b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c ourth parameter,
276c0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 eTextRep, speci
276d0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 fies what.** [SQ
276e0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 LITE_UTF8 | text
276f0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 encoding] this
27700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 SQL function pre
27710 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 fers for.** its
27720 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 parameters. Eve
27730 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ry SQL function
27740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
27750 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 ust be able to w
27760 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d ork.** with UTF-
27770 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 8, UTF-16le, or
27780 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 UTF-16be. But s
27790 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ome implementati
277a0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ons may be.** mo
277b0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 re efficient wit
277c0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 h one encoding t
277d0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 han another. ^A
277e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
277f0 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 y.** invoke sqli
27800 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
27810 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ion() or sqlite3
27820 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
27830 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 16() multiple.**
27840 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 times with the
27850 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 same function bu
27860 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 t with different
27870 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 values of eText
27880 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 Rep..** ^When mu
27890 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
278a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
278b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
278c0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 available, SQLit
278d0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 e.** will pick t
278e0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f he one that invo
278f0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 lves the least a
27900 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f mount of data co
27910 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 nversion..** If
27920 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 there is only a
27930 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 single implement
27940 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 ation which does
27950 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 not care what t
27960 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 ext.** encoding
27970 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 is used, then th
27980 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
27990 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c t should be [SQL
279a0 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 ITE_ANY]..**.**
279b0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 ^(The fifth para
279c0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 meter is an arbi
279d0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 trary pointer.
279e0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
279f0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e on of the.** fun
27a00 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 ction can gain a
27a10 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f ccess to this po
27a20 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c inter using [sql
27a30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
27a40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ].)^.**.** ^The
27a50 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 seventh, eighth
27a60 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 and ninth parame
27a70 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 ters, xFunc, xSt
27a80 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 ep and xFinal, a
27a90 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 re.** pointers t
27aa0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e o C-language fun
27ab0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c ctions that impl
27ac0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
27ad0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
27ae0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 regate. ^A scala
27af0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 r SQL function r
27b00 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
27b10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
27b20 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 xFunc.** callba
27b30 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f ck only; NULL po
27b40 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 inters must be p
27b50 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 assed as the xSt
27b60 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a ep and xFinal.**
27b70 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e parameters. ^An
27b80 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
27b90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
27ba0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
27bb0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 on of xStep.** a
27bc0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 nd xFinal and NU
27bd0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 LL pointer must
27be0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 be passed for xF
27bf0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 unc. ^To delete
27c00 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 an existing.** S
27c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
27c20 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e ggregate, pass N
27c30 55 4c 4c 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 ULL poiners for
27c40 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
27c50 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
27c60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
27c70 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 tenth parameter
27c80 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
27c90 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
27ca0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
27cb0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
27cc0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
27cd0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
27ce0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
27cf0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
27d00 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
27d10 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
27d20 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
27d30 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
27d40 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
27d50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27d60 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
27d70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
27d80 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
27d90 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
27da0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27db0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
27dc0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
27dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
27de0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
27df0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
27e00 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
27e10 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
27e20 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
27e30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
27e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
27e50 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
27e60 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
27e70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
27e80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
27e90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
27ea0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
27eb0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
27ec0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
27ed0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
27ee0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
27ef0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
27f00 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
27f10 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
27f20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
27f30 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
27f40 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
27f50 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
27f60 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
27f70 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
27f80 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
27f90 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
27fa0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
27fb0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
27fc0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
27fd0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
27fe0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
27ff0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
28000 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
28010 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
28020 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
28030 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
28040 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
28050 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
28060 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
28070 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
28080 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
28090 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
280a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
280b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
280c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
280d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
280e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
280f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
28100 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
28110 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
28120 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
28130 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
28140 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
28150 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
28160 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
28170 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
28180 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
28190 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
281a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
281b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
281c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
281d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
281e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
281f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
28200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
28210 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
28220 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
28230 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
28240 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
28250 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
28260 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
28270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
28280 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
28290 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
282a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
282b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
282c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
282d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
282e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
282f0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
28300 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
28310 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
28320 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
28330 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
28340 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
28350 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
28360 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
28370 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
28380 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
28390 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
283a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
283b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
283c0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
283d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
283e0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
283f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
28400 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
28410 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
28420 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
28430 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
28440 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
28450 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
28460 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
28470 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
28480 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
28490 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
284a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
284b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
284c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
284d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
284e0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
284f0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
28500 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
28510 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
28520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
28530 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
28540 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
28550 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
28560 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
28570 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
28580 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
28590 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
285a0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
285b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
285c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
285d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
285e0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
285f0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
28600 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
28610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28620 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
28630 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
28640 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
28650 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
28660 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
28670 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
28680 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
28690 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
286a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
286b0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
286c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
286d0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
286e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
286f0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 UTF16BE 3
28700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
28710 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
28720 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
28730 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
28740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
28750 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
28760 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
28770 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e eate_function on
28780 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
28790 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
287a0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 ED 8 /* sqli
287b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
287c0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
287d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
287e0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
287f0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
28800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
28810 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
28820 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
28830 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
28840 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
28850 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
28860 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
28870 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
28880 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
28890 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
288a0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
288b0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
288c0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
288d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
288e0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
288f0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
28900 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
28910 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
28920 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
28930 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 tell you what t
28940 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
28950 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
28960 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
28970 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
28980 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
28990 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f e_count(sqlite3_
289a0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
289b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
289c0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 sqlite3_expired
289d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
289e0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
289f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 ED int sqlite3_t
28a00 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 ransfer_bindings
28a10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
28a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
28a30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
28a40 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c D int sqlite3_gl
28a50 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 obal_recover(voi
28a60 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
28a70 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
28a80 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
28a90 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
28aa0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
28ab0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c qlite3_memory_al
28ac0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 arm(void(*)(void
28ad0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c *,sqlite3_int64,
28ae0 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 int),void*,sqlit
28af0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 e3_int64);.#endi
28b00 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
28b10 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c F: Obtaining SQL
28b20 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 Function Parame
28b30 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a ter Values.**.**
28b40 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
28b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
28b60 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
28b70 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
28b80 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
28b90 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
28ba0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
28bb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
28bc0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
28bd0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
28be0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gate..**.** The
28bf0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 xFunc (for scala
28c00 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 r functions) or
28c10 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 xStep (for aggre
28c20 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 gates) parameter
28c30 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
28c40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
28c50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
28c60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
28c70 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 16()].** define
28c80 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 callbacks that i
28c90 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
28ca0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
28cb0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 ggregates..** Th
28cc0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
28cd0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 to these callbac
28ce0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ks is an array o
28cf0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a f pointers to.**
28d00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
28d10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
28d20 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e ts. There is on
28d30 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
28d40 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 ] object for.**
28d50 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 each parameter t
28d60 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
28d70 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 on. These routi
28d80 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a nes are used to.
28d90 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 ** extract value
28da0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 s from the [sqli
28db0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
28dc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ts..**.** These
28dd0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e routines work on
28de0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 ly with [protect
28df0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
28e00 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e ] objects..** An
28e10 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 y attempt to use
28e20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
28e30 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 on an [unprotect
28e40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
28e50 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 ].** object resu
28e60 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
28e70 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
28e80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
28e90 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 work just like
28ea0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
28eb0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 g [column access
28ec0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 functions].** e
28ed0 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 xcept that thes
28ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 e routines take
28ef0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 a single [protec
28f00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
28f10 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 e] object.** poi
28f20 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 nter instead of
28f30 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a a [sqlite3_stmt*
28f40 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e ] pointer and an
28f50 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 integer column
28f60 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 number..**.** ^T
28f70 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
28f80 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 _text16() interf
28f90 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 ace extracts a U
28fa0 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 TF-16 string.**
28fb0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
28fc0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 te-order of the
28fd0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e host machine. ^
28fe0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 The.** sqlite3_v
28ff0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 alue_text16be()
29000 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 and sqlite3_valu
29010 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 e_text16le() int
29020 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 erfaces.** extra
29030 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ct UTF-16 string
29040 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 s as big-endian
29050 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 and little-endia
29060 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a n respectively..
29070 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
29080 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
29090 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 c_type() interfa
290a0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 ce attempts to a
290b0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 pply.** numeric
290c0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 affinity to the
290d0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 value. This mea
290e0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d ns that an attem
290f0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f pt is.** made to
29100 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c convert the val
29110 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 ue to an integer
29120 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 or floating poi
29130 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 nt. If.** such
29140 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 a conversion is
29150 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 possible without
29160 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 loss of informa
29170 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a tion (in other.*
29180 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 * words, if the
29190 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e value is a strin
291a0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b g that looks lik
291b0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 e a number).** t
291c0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 hen the conversi
291d0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e on is performed.
291e0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 Otherwise no c
291f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
29200 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ..** The [SQLITE
29210 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
29220 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 ype] after conve
29230 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 rsion is returne
29240 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 d.)^.**.** Pleas
29250 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 e pay particular
29260 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 attention to th
29270 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 e fact that the
29280 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 pointer returned
29290 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
292a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 3_value_blob()],
292b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
292c0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b text()], or.** [
292d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
292e0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 xt16()] can be i
292f0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 nvalidated by a
29300 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
29310 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 to.** [sqlite3_v
29320 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b alue_bytes()], [
29330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
29340 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 tes16()], [sqlit
29350 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
29360 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
29370 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
29380 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
29390 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
293a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
293b0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a ame thread as.**
293c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
293d0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 n that supplied
293e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
293f0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e ue*] parameters.
29400 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
29410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
29420 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
29430 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
29440 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 value_bytes(sqli
29450 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
29460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
29470 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 ytes16(sqlite3_v
29480 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 alue*);.double s
29490 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 qlite3_value_dou
294a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble(sqlite3_valu
294b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
294c0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 _value_int(sqlit
294d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 e3_value*);.sqli
294e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
294f0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 3_value_int64(sq
29500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
29510 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
29520 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 ar *sqlite3_valu
29530 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
29540 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
29550 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
29560 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 e_text16(sqlite3
29570 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
29580 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
29590 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c lue_text16le(sql
295a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
295b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
295c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
295d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
295e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
295f0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 lue_type(sqlite3
29600 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
29610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
29620 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 ric_type(sqlite3
29630 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
29640 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
29650 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 n Aggregate Func
29660 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a tion Context.**.
29670 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** Implementatio
29680 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 ns of aggregate
29690 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
296a0 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e e this.** routin
296b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
296c0 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 mory for storing
296d0 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a their state..**
296e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 .** ^The first t
296f0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f ime the sqlite3_
29700 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
29710 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 t(C,N) routine i
29720 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 s called .** for
29730 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 a particular ag
29740 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
29750 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f , SQLite.** allo
29760 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 cates N of memor
29770 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 y, zeroes out th
29780 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 at memory, and r
29790 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
297a0 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d .** to the new m
297b0 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e emory. ^On secon
297c0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
297d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
297e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
297f0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 ontext() for the
29800 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
29810 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 function instanc
29820 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 e,.** the same b
29830 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 uffer is returne
29840 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 d. Sqlite3_aggr
29850 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
29860 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 is normally.** c
29870 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 alled once for e
29880 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ach invocation o
29890 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c f the xStep call
298a0 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e back and then on
298b0 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 e.** last time w
298c0 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 hen the xFinal c
298d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
298e0 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 ed. ^(When no r
298f0 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 ows match.** an
29900 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c aggregate query,
29910 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c the xStep() cal
29920 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 lback of the agg
29930 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a regate function.
29940 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
29950 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 n is never calle
29960 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 d and xFinal() i
29970 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 s called exactly
29980 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f once..** In tho
29990 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 se cases, sqlite
299a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
299b0 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 ext() might be c
299c0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a alled for the.**
299d0 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d first time from
299e0 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 within xFinal()
299f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
29a00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
29a10 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f _context(C,N) ro
29a20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
29a30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
29a40 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 N is.** less tha
29a50 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
29a60 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 ro or if a memor
29a70 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 y allocate error
29a80 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e occurs..**.** ^
29a90 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 (The amount of s
29aa0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 pace allocated b
29ab0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 y sqlite3_aggreg
29ac0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
29ad0 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 is.** determine
29ae0 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d d by the N param
29af0 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 eter on first su
29b00 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 ccessful call.
29b10 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 Changing the.**
29b20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 value of N in su
29b30 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
29b40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
29b50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 te_context() wit
29b60 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 hin.** the same
29b70 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
29b80 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c on instance will
29b90 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 not resize the
29ba0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
29bb0 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 tion.)^.**.** ^S
29bc0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
29bd0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 lly frees the me
29be0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 mory allocated b
29bf0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 y .** sqlite3_ag
29c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
29c10 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 ) when the aggre
29c20 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c gate query concl
29c30 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 udes..**.** The
29c40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
29c50 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f must be a copy o
29c60 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
29c70 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
29c80 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
29c90 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
29ca0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
29cb0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 to the xStep or
29cc0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
29cd0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
29ce0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
29cf0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 regate.** functi
29d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 on..**.** This r
29d10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
29d20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
29d30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
29d40 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 ich.** the aggre
29d50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
29d60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
29d70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 .void *sqlite3_a
29d80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
29d90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29da0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
29db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29dc0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
29dd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
29de0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 The sqlite3_user
29df0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 _data() interfac
29e00 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
29e10 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
29e20 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
29e30 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 pUserData parame
29e40 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 ter (the 5th par
29e50 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
29e60 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
29e70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
29e80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
29e90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
29ea0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
29eb0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
29ec0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
29ed0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
29ee0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
29ef0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
29f00 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
29f10 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
29f20 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
29f30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
29f40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
29f50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 is running..*/.v
29f60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 oid *sqlite3_use
29f70 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 r_data(sqlite3_c
29f80 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
29f90 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
29fa0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 ase Connection F
29fb0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a or Functions.**.
29fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
29fd0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
29fe0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 e() interface re
29ff0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
2a000 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
2a010 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
2a020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 connection] (the
2a030 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 1st parameter).
2a040 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
2a050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2a060 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 on()].** and [sq
2a070 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2a080 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 ction16()] routi
2a090 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 nes that origina
2a0a0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 lly.** registere
2a0b0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
2a0c0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n defined functi
2a0d0 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a on..*/.sqlite3 *
2a0e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
2a0f0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
2a100 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 3_context*);../*
2a110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
2a120 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 nction Auxiliary
2a130 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Data.**.** The
2a140 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 following two fu
2a150 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 nctions may be u
2a160 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 sed by scalar SQ
2a170 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a L functions to.*
2a180 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 * associate meta
2a190 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 data with argume
2a1a0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 nt values. If th
2a1b0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 e same value is
2a1c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c passed to.** mul
2a1d0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e tiple invocation
2a1e0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 s of the same SQ
2a1f0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e L function durin
2a200 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f g query executio
2a210 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 n, under.** some
2a220 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 circumstances t
2a230 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 he associated me
2a240 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 tadata may be pr
2a250 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 eserved. This ma
2a260 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f y.** be used, fo
2a270 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 r example, to ad
2a280 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 d a regular-expr
2a290 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 ession matching
2a2a0 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 scalar.** functi
2a2b0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 on. The compiled
2a2c0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
2a2d0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
2a2e0 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a on is stored as.
2a2f0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f ** metadata asso
2a300 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2a310 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 SQL value passed
2a320 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 as the regular
2a330 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 expression.** pa
2a340 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 ttern. The comp
2a350 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 iled regular exp
2a360 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 ression can be r
2a370 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c eused on multipl
2a380 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 e.** invocations
2a390 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
2a3a0 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 ction so that th
2a3b0 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 e original patte
2a3c0 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 rn string.** doe
2a3d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
2a3e0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 recompiled on e
2a3f0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a ach invocation..
2a400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a410 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
2a420 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2a430 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2a440 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 the metadata.**
2a450 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 associated by th
2a460 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
2a470 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e xdata() function
2a480 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 with the Nth ar
2a490 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 gument.** value
2a4a0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
2a4b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2a4c0 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 ion. ^If no meta
2a4d0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 data has been ev
2a4e0 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 er.** been set f
2a4f0 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d or the Nth argum
2a500 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 ent of the funct
2a510 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 ion, or if the c
2a520 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
2a530 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
2a540 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 er has changed s
2a550 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 ince the meta-da
2a560 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 ta was set,.** t
2a570 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hen sqlite3_get_
2a580 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e auxdata() return
2a590 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2a5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2a5b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
2a5c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 () interface sav
2a5d0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a es the metadata.
2a5e0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
2a5f0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
2a600 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 er as the metada
2a610 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a ta for the N-th.
2a620 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 ** argument of t
2a630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2a640 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
2a650 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 Subsequent.**
2a660 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2a670 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d _get_auxdata() m
2a680 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 ight return this
2a690 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 data, if it has
2a6a0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 .** not been des
2a6b0 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 troyed..** ^If i
2a6c0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 t is not NULL, S
2a6d0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
2a6e0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
2a6f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 .** function giv
2a700 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 en by the 4th pa
2a710 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2a720 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
2a730 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 on.** the metad
2a740 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 ata when the cor
2a750 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 responding funct
2a760 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 ion parameter ch
2a770 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e anges.** or when
2a780 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2a790 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 nt completes, wh
2a7a0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
2a7b0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 rst..**.** SQLit
2a7c0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c e is free to cal
2a7d0 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 l the destructor
2a7e0 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 and drop metada
2a7f0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 ta on any.** par
2a800 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 ameter of any fu
2a810 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 nction at any ti
2a820 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 me. ^The only g
2a830 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 uarantee is that
2a840 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 .** the destruct
2a850 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 or will be calle
2a860 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 d before the met
2a870 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 adata is dropped
2a880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 ..**.** ^(In pra
2a890 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 ctice, metadata
2a8a0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 is preserved bet
2a8b0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 ween function ca
2a8c0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 lls for.** expre
2a8d0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ssions that are
2a8e0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 constant at comp
2a8f0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 ile time. This i
2a900 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a ncludes literal.
2a910 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 ** values and [p
2a920 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a arameters].)^.**
2a930 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2a940 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
2a950 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
2a960 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
2a970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
2a980 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
2a990 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
2a9a0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _get_auxdata(sql
2a9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2a9c0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 nt N);.void sqli
2a9d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
2a9e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2a9f0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 , int N, void*,
2aa00 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 void (*)(void*))
2aa10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
2aa20 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 EF: Constants De
2aa30 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 fining Special D
2aa40 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 estructor Behavi
2aa50 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 or.**.** These a
2aa60 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 re special value
2aa70 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 s for the destru
2aa80 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 ctor that is pas
2aa90 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a sed in as the.**
2aaa0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 final argument
2aab0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 to routines like
2aac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2aad0 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 _blob()]. ^If t
2aae0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
2aaf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
2ab00 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
2ab10 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
2ab20 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
2ab30 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
2ab40 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
2ab50 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
2ab60 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
2ab70 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 royed. ^The.**
2ab80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
2ab90 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 value means tha
2aba0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 t the content wi
2abb0 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 ll likely change
2abc0 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 in.** the near
2abd0 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 future and that
2abe0 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 SQLite should ma
2abf0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ke its own priva
2ac00 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 te copy of.** th
2ac10 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 e content before
2ac20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
2ac30 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 * The typedef is
2ac40 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f necessary to wo
2ac50 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 rk around proble
2ac60 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a ms in certain.**
2ac70 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 C++ compilers.
2ac80 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 See ticket #219
2ac90 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 1..*/.typedef vo
2aca0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 id (*sqlite3_des
2acb0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f tructor_type)(vo
2acc0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 id*);.#define SQ
2acd0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 LITE_STATIC
2ace0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
2acf0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 uctor_type)0).#d
2ad00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
2ad10 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 NSIENT ((sqlit
2ad20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
2ad30 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 pe)-1)../*.** CA
2ad40 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 PI3REF: Setting
2ad50 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e The Result Of An
2ad60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a SQL Function.**
2ad70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2ad80 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 es are used by t
2ad90 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e he xFunc or xFin
2ada0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 al callbacks tha
2adb0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 t.** implement S
2adc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
2add0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 aggregates. Se
2ade0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 e.** [sqlite3_cr
2adf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
2ae00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
2ae10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
2ae20 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 )].** for additi
2ae30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
2ae40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 ..**.** These fu
2ae50 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 nctions work ver
2ae60 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 y much like the
2ae70 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 [parameter bindi
2ae80 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a ng] family of.**
2ae90 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 functions used
2aea0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 to bind values t
2aeb0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 o host parameter
2aec0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 s in prepared st
2aed0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 atements..** Ref
2aee0 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 er to the [SQL p
2aef0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 arameter] docume
2af00 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
2af10 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
2af20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
2af30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
2af40 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ob() interface s
2af50 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
2af60 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
2af70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2af80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
2af90 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 BLOB whose cont
2afa0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a ent is pointed.*
2afb0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f * to by the seco
2afc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
2afd0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 which is N byte
2afe0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 s long where N i
2aff0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 s the.** third p
2b000 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2b010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
2b020 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 ult_zeroblob() i
2b030 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 nterfaces set th
2b040 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
2b050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2b060 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
2b070 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e to be a BLOB con
2b080 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f taining all zero
2b090 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 .** bytes and N
2b0a0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 bytes in size, w
2b0b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 here N is the va
2b0c0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 lue of the 2nd p
2b0d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2b0e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
2b0f0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 ult_double() int
2b100 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
2b110 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
2b120 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
2b130 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
2b140 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 o be a floating
2b150 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 point value spec
2b160 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 ified.** by its
2b170 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
2b180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b190 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
2b1a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
2b1b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e lt_error16() fun
2b1c0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 ctions.** cause
2b1d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 the implemented
2b1e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
2b1f0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 throw an excepti
2b200 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 on..** ^SQLite u
2b210 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 ses the string p
2b220 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
2b230 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 .** 2nd paramete
2b240 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 r of sqlite3_res
2b250 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 ult_error() or s
2b260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2b270 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 ror16().** as th
2b280 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 e text of an err
2b290 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 or message. ^SQ
2b2a0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 Lite interprets
2b2b0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
2b2c0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d sage string from
2b2d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2b2e0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 error() as UTF-8
2b2f0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 . ^SQLite.** int
2b300 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 erprets the stri
2b310 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
2b320 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
2b330 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 as UTF-16 in na
2b340 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 tive.** byte ord
2b350 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 er. ^If the thi
2b360 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
2b370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2b380 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
2b390 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2b3a0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 r16() is negativ
2b3b0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
2b3c0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 kes as the error
2b3d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 .** message all
2b3e0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 text up through
2b3f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
2b400 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 haracter..** ^If
2b410 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
2b420 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2b430 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
2b440 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 r.** sqlite3_res
2b450 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
2b460 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 non-negative th
2b470 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
2b480 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 that many.** byt
2b490 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
2b4a0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 rs) from the 2nd
2b4b0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
2b4c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
2b4d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b4e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
2b4f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
2b500 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
2b510 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 routines make a
2b520 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
2b530 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
2b540 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a e text before.**
2b550 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 they return. H
2b560 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e ence, the callin
2b570 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 g function can d
2b580 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 eallocate or.**
2b590 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 modify the text
2b5a0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 after they retur
2b5b0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a n without harm..
2b5c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b5d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
2b5e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 e() function cha
2b5f0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 nges the error c
2b600 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 ode.** returned
2b610 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 by SQLite as a r
2b620 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f esult of an erro
2b630 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e r in a function.
2b640 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a ^By default,.*
2b650 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 * the error code
2b660 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 is SQLITE_ERROR
2b670 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 . ^A subsequent
2b680 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
2b690 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
2b6a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
2b6b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
2b6c0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
2b6d0 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
2b6e0 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 RROR..**.** ^The
2b6f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2b700 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 toobig() interfa
2b710 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
2b720 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 to throw an err
2b730 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 or.** indicating
2b740 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f that a string o
2b750 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f r BLOB is too lo
2b760 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ng to represent.
2b770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b780 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d te3_result_nomem
2b790 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 () interface cau
2b7a0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
2b7b0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 row an error.**
2b7c0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
2b7d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
2b7e0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a ion failed..**.*
2b7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
2b800 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 esult_int() inte
2b810 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
2b820 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
2b830 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
2b840 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2b850 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d on to be the 32-
2b860 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
2b870 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
2b880 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
2b890 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 ument..** ^The s
2b8a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
2b8b0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 t64() interface
2b8c0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
2b8d0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
2b8e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2b8f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
2b900 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 be the 64-bit si
2b910 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
2b920 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
2b930 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
2b940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b950 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 te3_result_null(
2b960 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
2b970 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2b980 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
2b990 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2b9a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e function to be N
2b9b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ULL..**.** ^The
2b9c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2b9d0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 ext(), sqlite3_r
2b9e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a esult_text16(),.
2b9f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
2ba00 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e t_text16le(), an
2ba10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2ba20 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 _text16be() inte
2ba30 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 rfaces.** set th
2ba40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
2ba50 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
2ba60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2ba70 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 on to be.** a te
2ba80 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 xt string which
2ba90 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 is represented a
2baa0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 s UTF-8, UTF-16
2bab0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2bac0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 r,.** UTF-16 lit
2bad0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 tle endian, or U
2bae0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e TF-16 big endian
2baf0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a , respectively..
2bb00 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 ** ^SQLite takes
2bb10 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 the text result
2bb20 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 from the applic
2bb30 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 ation from.** th
2bb40 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
2bb50 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 of the sqlite3_r
2bb60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
2bb70 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 rfaces..** ^If t
2bb80 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
2bb90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
2bba0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
2bbb0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 erfaces.** is ne
2bbc0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c gative, then SQL
2bbd0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 ite takes result
2bbe0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 text from the 2
2bbf0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
2bc00 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 through the firs
2bc10 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 t zero character
2bc20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
2bc30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2bc40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2bc50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
2bc60 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 s.** is non-nega
2bc70 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 tive, then as ma
2bc80 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ny bytes (not ch
2bc90 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 aracters) of the
2bca0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 text.** pointed
2bcb0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 to by the 2nd p
2bcc0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b arameter are tak
2bcd0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 en as the applic
2bce0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a ation-defined.**
2bcf0 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 function result
2bd00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
2bd10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2bd20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2bd30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
2bd40 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
2bd50 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 result_blob is a
2bd60 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
2bd70 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 r, then SQLite c
2bd80 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e alls that.** fun
2bd90 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 ction as the des
2bda0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 tructor on the t
2bdb0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
2bdc0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a lt when it has.*
2bdd0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 * finished using
2bde0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
2bdf0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
2be00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
2be10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2be20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 t* interfaces or
2be30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 to.** sqlite3_r
2be40 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
2be50 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
2be60 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 nt SQLITE_STATIC
2be70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
2be80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
2be90 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
2bea0 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 esult is in cons
2beb0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 tant space and d
2bec0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 oes not.** copy
2bed0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
2bee0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 he parameter nor
2bef0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 call a destruct
2bf00 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e or on the conten
2bf10 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 t.** when it has
2bf20 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
2bf30 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
2bf40 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
2bf50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
2bf60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2bf70 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
2bf80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
2bf90 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
2bfa0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
2bfb0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a QLITE_TRANSIENT.
2bfc0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d ** then SQLite m
2bfd0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
2bfe0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 he result into s
2bff0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 pace obtained fr
2c000 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 om.** from [sqli
2c010 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 te3_malloc()] be
2c020 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e fore it returns.
2c030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2c040 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2c050 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
2c060 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a s the result of.
2c070 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
2c080 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2c090 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 ion to be a copy
2c0a0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 the.** [unprote
2c0b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2c0c0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 ue] object speci
2c0d0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
2c0e0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 parameter. ^The
2c0f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
2c100 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
2c110 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 face makes a cop
2c120 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
2c130 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 3_value].** so t
2c140 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
2c150 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 _value] specifie
2c160 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 d in the paramet
2c170 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 er may change or
2c180 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 .** be deallocat
2c190 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
2c1a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
2c1b0 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 returns without
2c1c0 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f harm..** ^A [pro
2c1d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2c1e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 alue] object may
2c1f0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 always be used
2c200 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 where an.** [unp
2c210 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2c220 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 _value] object i
2c230 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 s required, so e
2c240 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 ither.** kind of
2c250 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
2c260 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 object can be u
2c270 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e sed with this in
2c280 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 terface..**.** I
2c290 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2c2a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
2c2b0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 within the diff
2c2c0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 erent thread.**
2c2d0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e than the one con
2c2e0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c taining the appl
2c2f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2c300 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 function that re
2c310 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 ceived.** the [s
2c320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
2c330 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 pointer, the res
2c340 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
2c350 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 ed..*/.void sqli
2c360 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
2c370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2c380 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
2c390 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
2c3a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
2c3b0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
2c3c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2c3d0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 , double);.void
2c3e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2c3f0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e rror(sqlite3_con
2c400 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
2c410 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 r*, int);.void s
2c420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2c430 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ror16(sqlite3_co
2c440 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
2c450 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
2c460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2c470 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 rror_toobig(sqli
2c480 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
2c490 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2c4a0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 lt_error_nomem(s
2c4b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2c4c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
2c4d0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
2c4e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2c4f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
2c500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
2c510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2c520 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
2c530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
2c540 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 64(sqlite3_conte
2c550 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 xt*, sqlite3_int
2c560 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 64);.void sqlite
2c570 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 3_result_null(sq
2c580 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
2c590 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2c5a0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 sult_text(sqlite
2c5b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
2c5c0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f t char*, int, vo
2c5d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
2c5e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2c5f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
2c600 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
2c610 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
2c620 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
2c630 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2c640 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
2c650 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
2c660 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
2c670 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2c680 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2c690 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
2c6a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
2c6b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
2c6c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2c6d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2c6e0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
2c6f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
2c700 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
2c710 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2c720 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
2c730 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
2c740 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
2c750 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
2c760 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
2c770 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 nces.**.** ^Thes
2c780 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c e functions add,
2c790 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 remove, or modi
2c7a0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d fy a [collation]
2c7b0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
2c7c0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
2c7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
2c7e0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 ecified as the f
2c7f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
2c800 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
2c810 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 f the collation
2c820 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
2c830 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
2c840 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2c850 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
2c860 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2c870 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
2c880 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
2c890 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2c8a0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 r for sqlite3_cr
2c8b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
2c8c0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f ()..** ^Collatio
2c8d0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d n names that com
2c8e0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 pare equal accor
2c8f0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 ding to [sqlite3
2c900 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 _strnicmp()] are
2c910 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 .** considered t
2c920 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 o be the same na
2c930 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 me..**.** ^(The
2c940 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 third argument (
2c950 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 eTextRep) must b
2c960 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
2c970 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a stants:.** <ul>.
2c980 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
2c990 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b UTF8],.** <li> [
2c9a0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
2c9b0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
2c9c0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c _UTF16BE],.** <l
2c9d0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
2c9e0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
2c9f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
2ca00 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NED]..** </ul>)^
2ca10 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 .** ^The eTextRe
2ca20 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 p argument deter
2ca30 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 mines the encodi
2ca40 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 ng of strings pa
2ca50 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ssed.** to the c
2ca60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2ca70 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c n callback, xCal
2ca80 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b lback..** ^The [
2ca90 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e SQLITE_UTF16] an
2caa0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f d [SQLITE_UTF16_
2cab0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 ALIGNED] values
2cac0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 for eTextRep.**
2cad0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f force strings to
2cae0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e be UTF16 with n
2caf0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
2cb00 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
2cb10 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
2cb20 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 value for eText
2cb30 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e Rep forces strin
2cb40 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f gs to begin.** o
2cb50 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 n an even byte a
2cb60 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ddress..**.** ^T
2cb70 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
2cb80 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 20 61 nt, pArg, is a a
2cb90 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
2cba0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
2cbb0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 passed.** throug
2cbc0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 h as the first a
2cbd0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
2cbe0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2cbf0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a n callback..**.*
2cc00 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 * ^The fifth arg
2cc10 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b ument, xCallback
2cc20 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 , is a pointer t
2cc30 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 o the collating
2cc40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 function..** ^Mu
2cc50 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 ltiple collating
2cc60 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 functions can b
2cc70 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 e registered usi
2cc80 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 ng the same name
2cc90 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 but.** with dif
2cca0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
2ccb0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 parameters and S
2ccc0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 QLite will use w
2ccd0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 hichever.** func
2cce0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 tion requires th
2ccf0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
2cd00 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d f data transform
2cd10 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 ation..** ^If th
2cd20 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 e xCallback argu
2cd30 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 ment is NULL the
2cd40 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 n the collating
2cd50 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 function is.** d
2cd60 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 eleted. ^When a
2cd70 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e ll collating fun
2cd80 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 ctions having th
2cd90 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 e same name are
2cda0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 deleted,.** that
2cdb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f collation is no
2cdc0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a longer usable..
2cdd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 **.** ^The colla
2cde0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
2cdf0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
2ce00 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 d with a copy of
2ce10 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 the pArg .** ap
2ce20 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
2ce30 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 ointer and with
2ce40 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 two strings in t
2ce50 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 he encoding spec
2ce60 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
2ce70 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e eTextRep argumen
2ce80 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e t. The collatin
2ce90 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 g function must
2cea0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 return an.** int
2ceb0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 eger that is neg
2cec0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 ative, zero, or
2ced0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 positive.** if t
2cee0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 he first string
2cef0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 is less than, eq
2cf00 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 ual to, or great
2cf10 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f er than the seco
2cf20 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 nd,.** respectiv
2cf30 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e ely. A collatin
2cf40 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 g function must
2cf50 61 6c 77 61 79 20 72 65 74 75 72 6e 20 74 68 65 alway return the
2cf60 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 same answer.**
2cf70 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 given the same i
2cf80 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f nputs. If two o
2cf90 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 r more collating
2cfa0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 functions are r
2cfb0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 egistered.** to
2cfc0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 the same collati
2cfd0 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 on name (using d
2cfe0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
2cff0 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 p values) then a
2d000 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 ll.** must give
2d010 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e an equivalent an
2d020 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 swer when invoke
2d030 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e d with equivalen
2d040 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 t strings..** Th
2d050 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
2d060 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 tion must obey t
2d070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f he following pro
2d080 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a perties for all.
2d090 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c ** strings A, B,
2d0a0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f and C:.**.** <o
2d0b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d l>.** <li> If A=
2d0c0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a =B then B==A..**
2d0d0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e <li> If A==B an
2d0e0 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 d B==C then A==C
2d0f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c ..** <li> If A&l
2d100 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e t;B THEN B>A.
2d110 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 .** <li> If A<
2d120 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 ;B and B<C th
2d130 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f en A<C..** </
2d140 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 ol>.**.** If a c
2d150 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2d160 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 n fails any of t
2d170 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 he above constra
2d180 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a ints and that.**
2d190 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
2d1a0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 ion is register
2d1b0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 ed and used, the
2d1c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
2d1d0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 f SQLite.** is u
2d1e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2d1f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 ^The sqlite3_cre
2d200 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
2d210 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
2d220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2d230 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 lation().** with
2d240 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 the addition th
2d250 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 at the xDestroy
2d260 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
2d270 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e ked on pArg when
2d280 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e .** the collatin
2d290 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 g function is de
2d2a0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 leted..** ^Colla
2d2b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 ting functions a
2d2c0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 re deleted when
2d2d0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 they are overrid
2d2e0 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 den by later.**
2d2f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c calls to the col
2d300 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 lation creation
2d310 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 functions or whe
2d320 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 n the.** [databa
2d330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
2d340 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b s closed using [
2d350 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
2d360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 ..**.** ^The xDe
2d370 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 stroy callback i
2d380 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c s <u>not</u> cal
2d390 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 led if the .** s
2d3a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2d3b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e llation_v2() fun
2d3c0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 ction fails. Ap
2d3d0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
2d3e0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
2d3f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2d400 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e on_v2() with a n
2d410 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 on-NULL xDestroy
2d420 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
2d430 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 .** check the r
2d440 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 eturn code and d
2d450 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 ispose of the ap
2d460 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
2d470 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 ointer.** themse
2d480 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e lves rather than
2d490 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 expecting SQLit
2d4a0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 e to deal with i
2d4b0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 t for them..** T
2d4c0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 his is different
2d4d0 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 from every othe
2d4e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
2d4f0 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 ce. The inconsi
2d500 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e stency .** is un
2d510 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 fortunate but ca
2d520 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 nnot be changed
2d530 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
2d540 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 backwards .** c
2d550 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
2d560 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
2d570 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2d580 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 n_needed()] and
2d590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 [sqlite3_collati
2d5a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a on_needed16()]..
2d5b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
2d5c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
2d5d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2d5e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2d5f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
2d600 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
2d610 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
2d620 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
2d630 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
2d640 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
2d650 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2d660 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
2d670 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
2d680 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
2d690 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
2d6a0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
2d6b0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
2d6c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
2d6d0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
2d6e0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
2d6f0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
2d700 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
2d710 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2d720 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
2d730 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
2d740 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
2d750 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 extRep, . void
2d760 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 *pArg,. int(*xC
2d770 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
2d780 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
2d790 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
2d7a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d7b0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
2d7c0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ded Callbacks.**
2d7d0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 .** ^To avoid ha
2d7e0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 ving to register
2d7f0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 all collation s
2d800 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 equences before
2d810 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 a database.** ca
2d820 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e n be used, a sin
2d830 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e gle callback fun
2d840 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
2d850 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 istered with the
2d860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
2d870 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 nnection] to be
2d880 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
2d890 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
2d8a0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
2d8b0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
2d8c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
2d8d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
2d8e0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
2d8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2d900 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
2d910 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
2d920 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
2d930 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
2d940 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
2d950 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
2d960 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
2d970 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ^If sqlite3_coll
2d980 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
2d990 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
2d9a0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
2d9b0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
2d9c0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
2d9d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 te order..** ^A
2d9e0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 call to either f
2d9f0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
2da00 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f the existing co
2da10 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 llation-needed c
2da20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
2da30 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 (When the callba
2da40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
2da50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2da60 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
2da70 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
2da80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
2da90 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2daa0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
2dab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2dac0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
2dad0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
2dae0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
2daf0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
2db00 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
2db10 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
2db20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
2db30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
2db40 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
2db50 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
2db60 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
2db70 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
2db80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
2db90 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
2dba0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
2dbb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2dbc0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
2dbd0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
2dbe0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
2dbf0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ence.)^.**.** Th
2dc00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
2dc10 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 ion should regis
2dc20 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 ter the desired
2dc30 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a collation using.
2dc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
2dc50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c te_collation()],
2dc60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2dc70 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c _collation16()],
2dc80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2dc90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2dca0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 _v2()]..*/.int s
2dcb0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2dcc0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
2dcd0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
2dce0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
2dcf0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
2dd00 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
2dd10 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
2dd20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2dd30 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
2dd40 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
2dd50 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
2dd60 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
2dd70 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
2dd80 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 ;..#ifdef SQLITE
2dd90 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a _HAS_CODEC./*.**
2dda0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 Specify the key
2ddb0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 for an encrypte
2ddc0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 d database. Thi
2ddd0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 s routine should
2dde0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 be.** called ri
2ddf0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 ght after sqlite
2de00 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_open()..**.**
2de10 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
2de20 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
2de30 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
2de40 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
2de50 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
2de60 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
2de70 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
2de80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2de90 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2dea0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
2deb0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
2dec0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
2ded0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
2dee0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
2def0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
2df00 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
2df10 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
2df20 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
2df30 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
2df40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
2df50 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
2df60 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
2df70 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
2df80 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
2df90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
2dfa0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
2dfb0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
2dfc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
2dfd0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
2dfe0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
2dff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2e000 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
2e010 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2e020 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2e030 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
2e040 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2e050 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
2e060 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
2e070 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
2e080 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 Specify the acti
2e090 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 vation key for a
2e0a0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 SEE database.
2e0b0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 Unless .** activ
2e0c0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 ated, none of th
2e0d0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 e SEE routines w
2e0e0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 ill work..*/.voi
2e0f0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 d sqlite3_activa
2e100 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 te_see(. const
2e110 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
2e120 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
2e130 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
2e140 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 .);.#endif..#ifd
2e150 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 ef SQLITE_ENABLE
2e160 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 _CEROD./*.** Spe
2e170 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 cify the activat
2e180 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 ion key for a CE
2e190 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 ROD database. U
2e1a0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 nless .** activa
2e1b0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 ted, none of the
2e1c0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 CEROD routines
2e1d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f will work..*/.vo
2e1e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 id sqlite3_activ
2e1f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e ate_cerod(. con
2e200 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 st char *zPassPh
2e210 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 rase /* A
2e220 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 ctivation phrase
2e230 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f */.);.#endif../
2e240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2e250 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e uspend Execution
2e260 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d For A Short Tim
2e270 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
2e280 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 te3_sleep() func
2e290 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 tion causes the
2e2a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 current thread t
2e2b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 o suspend execut
2e2c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 ion.** for at le
2e2d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 ast a number of
2e2e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 milliseconds spe
2e2f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 cified in its pa
2e300 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
2e310 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 f the operating
2e320 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 system does not
2e330 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 support sleep re
2e340 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d quests with.** m
2e350 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
2e360 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
2e370 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
2e380 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a e rounded up to.
2e390 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 ** the nearest s
2e3a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 econd. The numbe
2e3b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2e3c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 s of sleep actua
2e3d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 lly.** requested
2e3e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 from the operat
2e3f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 ing system is re
2e400 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 turned..**.** ^S
2e410 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 QLite implements
2e420 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2e430 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 by calling the x
2e440 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f Sleep().** metho
2e450 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
2e460 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
2e470 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 bject. If the x
2e480 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a Sleep() method.*
2e490 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 * of the default
2e4a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c VFS is not impl
2e4b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c emented correctl
2e4c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d y, or not implem
2e4d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c ented at.** all,
2e4e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2e4f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c or of sqlite3_sl
2e500 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 eep() may deviat
2e510 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 e from the descr
2e520 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 iption.** in the
2e530 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 previous paragr
2e540 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c aphs..*/.int sql
2e550 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b ite3_sleep(int);
2e560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e570 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f : Name Of The Fo
2e580 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d lder Holding Tem
2e590 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a porary Files.**.
2e5a0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f ** ^(If this glo
2e5b0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
2e5c0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
2e5d0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
2e5e0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
2e5f0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e f a folder (a.k.
2e600 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 a. directory), t
2e610 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 hen all temporar
2e620 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 y files.** creat
2e630 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 ed by SQLite whe
2e640 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d n using a built-
2e650 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 in [sqlite3_vfs
2e660 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 | VFS].** will b
2e670 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 e placed in that
2e680 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e directory.)^ ^
2e690 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 If this variable
2e6a0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
2e6b0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
2e6c0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 te performs a se
2e6d0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 arch for an appr
2e6e0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f opriate.** tempo
2e6f0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 rary file direct
2e700 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 ory..**.** It is
2e710 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 not safe to rea
2e720 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 d or modify this
2e730 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 variable in mor
2e740 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 e than one.** th
2e750 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 read at a time.
2e760 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
2e770 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
2e780 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a y this variable.
2e790 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 ** if a [databas
2e7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
2e7b0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 being used at t
2e7c0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 he same time in
2e7d0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 a separate.** th
2e7e0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 read..** It is i
2e7f0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 ntended that thi
2e800 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 s variable be se
2e810 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 t once.** as par
2e820 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 t of process ini
2e830 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 tialization and
2e840 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 before any SQLit
2e850 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 e interface.** r
2e860 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 outines have bee
2e870 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 n called and tha
2e880 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
2e890 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
2e8a0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a .** thereafter..
2e8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 **.** ^The [temp
2e8c0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
2e8d0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 pragma] may mod
2e8e0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
2e8f0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 e and cause.** i
2e900 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 t to point to me
2e910 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
2e920 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2e930 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f oc]. ^Furthermo
2e940 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 re,.** the [temp
2e950 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
2e960 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 pragma] always
2e970 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 assumes that any
2e980 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 string.** that
2e990 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f this variable po
2e9a0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 ints to is held
2e9b0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e in memory obtain
2e9c0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
2e9d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 ite3_malloc] and
2e9e0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 the pragma may
2e9f0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 attempt to free
2ea00 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 that memory.** u
2ea10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
2ea20 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 ee]..** Hence, i
2ea30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 f this variable
2ea40 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 is modified dire
2ea50 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 ctly, either it
2ea60 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 should be.** mad
2ea70 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 e NULL or made t
2ea80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
2ea90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2eaa0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
2eab0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 .** or else the
2eac0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 use of the [temp
2ead0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
2eae0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 pragma] should
2eaf0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 be avoided..*/.S
2eb00 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
2eb10 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f r *sqlite3_temp_
2eb20 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
2eb30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
2eb40 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 For Auto-Commit
2eb50 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 Mode.** KEYWORD
2eb60 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d S: {autocommit m
2eb70 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ode}.**.** ^The
2eb80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f sqlite3_get_auto
2eb90 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 commit() interfa
2eba0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ce returns non-z
2ebb0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 ero or.** zero i
2ebc0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 f the given data
2ebd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2ebe0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 is or is not in
2ebf0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c autocommit mode,
2ec00 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
2ec10 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d . ^Autocommit m
2ec20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
2ec30 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ault..** ^Autoco
2ec40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
2ec50 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
2ec60 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
2ec70 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
2ec80 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 e is re-enabled
2ec90 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 by a [COMMIT] or
2eca0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a [ROLLBACK]..**.
2ecb0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 ** If certain ki
2ecc0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 nds of errors oc
2ecd0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 cur on a stateme
2ece0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 nt within a mult
2ecf0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 i-statement.** t
2ed00 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f ransaction (erro
2ed10 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 rs including [SQ
2ed20 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c LITE_FULL], [SQL
2ed30 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b ITE_IOERR],.** [
2ed40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b SQLITE_NOMEM], [
2ed50 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e SQLITE_BUSY], an
2ed60 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 d [SQLITE_INTERR
2ed70 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a UPT]) then the.*
2ed80 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 * transaction mi
2ed90 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ght be rolled ba
2eda0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
2edb0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 . The only way
2edc0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 to.** find out w
2edd0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 hether SQLite au
2ede0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
2edf0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e ed back the tran
2ee00 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a saction after.**
2ee10 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 an error is to
2ee20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f use this functio
2ee30 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 n..**.** If anot
2ee40 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
2ee50 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
2ee60 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
2ee70 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2ee80 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 ection while thi
2ee90 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e s routine is run
2eea0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ning, then the r
2eeb0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 eturn value.** i
2eec0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a s undefined..*/.
2eed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
2eee0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 autocommit(sqlit
2eef0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
2ef00 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 I3REF: Find The
2ef10 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 Database Handle
2ef20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 Of A Prepared St
2ef30 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 atement.**.** ^T
2ef40 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 he sqlite3_db_ha
2ef50 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 ndle interface r
2ef60 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 eturns the [data
2ef70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2ef80 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 handle.** to wh
2ef90 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 ich a [prepared
2efa0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e statement] belon
2efb0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 gs. ^The [datab
2efc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
2efd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2efe0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
2eff0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 is the same [da
2f000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f010 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 n].** that was t
2f020 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2f030 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
2f040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2f050 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
2f060 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
2f070 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
2f080 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
2f090 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
2f0a0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 place..*/.sqlite
2f0b0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
2f0c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
2f0d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2f0e0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 3REF: Find the n
2f0f0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ext prepared sta
2f100 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 tement.**.** ^Th
2f110 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
2f120 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2f130 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 o the next [prep
2f140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2f150 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 after.** pStmt a
2f160 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
2f170 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2f180 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e nection] pDb. ^
2f190 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c If pStmt is NULL
2f1a0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e .** then this in
2f1b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2f1c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2f1d0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 first prepared
2f1e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 statement.** ass
2f1f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
2f200 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2f210 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e tion pDb. ^If n
2f220 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 o prepared state
2f230 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 ment.** satisfie
2f240 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 s the conditions
2f250 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
2f260 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c , it returns NUL
2f270 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 L..**.** The [da
2f280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f290 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 n] pointer D in
2f2a0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
2f2b0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2f2c0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 D,S)] must refer
2f2d0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 to an open data
2f2e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
2f2f0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 on and in partic
2f300 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 ular must not be
2f310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2f320 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 .*/.sqlite3_stmt
2f330 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 *sqlite3_next_s
2f340 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 tmt(sqlite3 *pDb
2f350 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a , sqlite3_stmt *
2f360 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2f370 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 API3REF: Commit
2f380 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 And Rollback Not
2f390 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 ification Callba
2f3a0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 cks.**.** ^The s
2f3b0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2f3c0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
2f3d0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
2f3e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
2f3f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 to be invoked wh
2f400 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 enever a transac
2f410 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 tion is [COMMIT
2f420 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a | committed]..**
2f430 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 ^Any callback s
2f440 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
2f450 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
2f460 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a _commit_hook().*
2f470 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2f480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f490 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2f4a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2f4b0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2f4c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2f4d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2f4e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2f4f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2f500 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2f510 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c n is [ROLLBACK |
2f520 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a rolled back]..*
2f530 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 * ^Any callback
2f540 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
2f550 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
2f560 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
2f570 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
2f580 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2f590 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
2f5a0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 den..** ^The pAr
2f5b0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 g argument is pa
2f5c0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 ssed through to
2f5d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a the callback..**
2f5e0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
2f5f0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f k on a commit ho
2f600 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 ok function retu
2f610 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a rns non-zero,.**
2f620 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 then the commit
2f630 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e is converted in
2f640 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a to a rollback..*
2f650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2f660 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 3_commit_hook(D,
2f670 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 C,P) and sqlite3
2f680 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 _rollback_hook(D
2f690 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a ,C,P) functions.
2f6a0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 ** return the P
2f6b0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 argument from th
2f6c0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
2f6d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
2f6e0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 tion.** on the s
2f6f0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
2f700 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 nnection] D, or
2f710 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 NULL for.** the
2f720 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 first call for e
2f730 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 ach function on
2f740 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c D..**.** The cal
2f750 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 lback implementa
2f760 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f tion must not do
2f770 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
2f780 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
2f790 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2f7a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
2f7b0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e ed the callback.
2f7c0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a Any actions.**
2f7d0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 to modify the d
2f7e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f7f0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 on must be defer
2f800 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 red until after
2f810 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f the.** completio
2f820 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
2f830 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 3_step()] call t
2f840 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
2f850 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 e commit.** or r
2f860 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 ollback hook in
2f870 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e the first place.
2f880 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
2f890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2f8a0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
2f8b0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
2f8c0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
2f8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f8e0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
2f8f0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
2f900 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
2f910 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 h..**.** ^Regist
2f920 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e ering a NULL fun
2f930 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 ction disables t
2f940 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
2f950 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d ** ^When the com
2f960 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 mit hook callbac
2f970 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e k routine return
2f980 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d s zero, the [COM
2f990 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f MIT].** operatio
2f9a0 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 n is allowed to
2f9b0 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c continue normall
2f9c0 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d y. ^If the comm
2f9d0 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 it hook.** retur
2f9e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
2f9f0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 n the [COMMIT] i
2fa00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
2fa10 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a a [ROLLBACK]..*
2fa20 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 * ^The rollback
2fa30 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 hook is invoked
2fa40 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 on a rollback th
2fa50 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 at results from
2fa60 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b a commit.** hook
2fa70 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a returning non-z
2fa80 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 ero, just as it
2fa90 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e would be with an
2faa0 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b y other rollback
2fab0 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ..**.** ^For the
2fac0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
2fad0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 s API, a transac
2fae0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 tion is said to
2faf0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c have been.** rol
2fb00 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 led back if an e
2fb10 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 xplicit "ROLLBAC
2fb20 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 K" statement is
2fb30 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 executed, or.**
2fb40 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 an error or cons
2fb50 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e traint causes an
2fb60 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 implicit rollba
2fb70 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 ck to occur..**
2fb80 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 ^The rollback ca
2fb90 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e llback is not in
2fba0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 voked if a trans
2fbb0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 action is.** aut
2fbc0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
2fbd0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 d back because t
2fbe0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2fbf0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
2fc00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2fc10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 the [sqlite3_up
2fc20 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 date_hook()] int
2fc30 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 erface..*/.void
2fc40 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f *sqlite3_commit_
2fc50 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 hook(sqlite3*, i
2fc60 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
2fc70 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 id*);.void *sqli
2fc80 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
2fc90 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 k(sqlite3*, void
2fca0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 (*)(void *), voi
2fcb0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
2fcc0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 3REF: Data Chang
2fcd0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 e Notification C
2fce0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
2fcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 The sqlite3_upda
2fd00 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 te_hook() interf
2fd10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
2fd20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2fd30 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 n.** with the [d
2fd40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2fd50 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 on] identified b
2fd60 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
2fd70 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e ment.** to be in
2fd80 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2fd90 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c row is updated,
2fda0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
2fdb0 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 eted..** ^Any ca
2fdc0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
2fdd0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2fde0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
2fdf0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2fe00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2fe10 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2fe20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
2fe30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2fe40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2fe50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 function to inv
2fe60 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f oke when a.** ro
2fe70 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
2fe80 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
2fe90 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 d..** ^The first
2fea0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2feb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
2fec0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
2fed0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2fee0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2fef0 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 ook()..** ^The s
2ff00 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 econd callback a
2ff10 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
2ff20 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 f [SQLITE_INSERT
2ff30 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 ], [SQLITE_DELET
2ff40 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 E],.** or [SQLIT
2ff50 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e E_UPDATE], depen
2ff60 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 ding on the oper
2ff70 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 ation that cause
2ff80 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a d the callback.*
2ff90 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e * to be invoked.
2ffa0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 .** ^The third a
2ffb0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 nd fourth argume
2ffc0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 nts to the callb
2ffd0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e ack contain poin
2ffe0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 ters to the.** d
2fff0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c atabase and tabl
30000 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e e name containin
30010 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 g the affected r
30020 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 ow..** ^The fina
30030 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d l callback param
30040 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 eter is the [row
30050 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a id] of the row..
30060 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 ** ^In the case
30070 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 of an update, th
30080 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 is is the [rowid
30090 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 ] after the upda
300a0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a te takes place..
300b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 **.** ^(The upda
300c0 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 te hook is not i
300d0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 nvoked when inte
300e0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c rnal system tabl
300f0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 es are.** modifi
30100 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f ed (i.e. sqlite_
30110 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 master and sqlit
30120 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a e_sequence).)^.*
30130 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 *.** ^In the cur
30140 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
30150 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 ion, the update
30160 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 hook.** is not i
30170 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c nvoked when dupl
30180 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 ication rows are
30190 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 deleted because
301a0 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f of an.** [ON CO
301b0 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 NFLICT | ON CONF
301c0 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c LICT REPLACE] cl
301d0 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 ause. ^Nor is t
301e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a he update hook.*
301f0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 * invoked when r
30200 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
30210 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 using the [trunc
30220 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
30230 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 ]..** The except
30240 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 ions defined in
30250 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d this paragraph m
30260 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 ight change in a
30270 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 future.** relea
30280 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a se of SQLite..**
30290 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 .** The update h
302a0 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ook implementati
302b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 on must not do a
302c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
302d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
302e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
302f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
30300 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b the update hook
30310 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
30320 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
30330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
30340 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
30350 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
30360 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
30370 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
30380 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
30390 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
303a0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a he update hook..
303b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
303c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
303d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
303e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
303f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
30400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30410 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
30420 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
30430 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
30440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
30450 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
30460 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e (D,C,P) function
30470 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
30480 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 P argument from
30490 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
304a0 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 l.** on the same
304b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
304c0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c ction] D, or NUL
304d0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 L for.** the fir
304e0 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a st call on D..**
304f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
30500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 [sqlite3_commit
30510 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 _hook()] and [sq
30520 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
30530 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 ook()].** interf
30540 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 aces..*/.void *s
30550 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
30560 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ok(. sqlite3*,
30570 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 . void(*)(void
30580 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 *,int ,char cons
30590 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a t *,char const *
305a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c ,sqlite3_int64),
305b0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a . void*.);../*.
305c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
305d0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
305e0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
305f0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b e.** KEYWORDS: {
30600 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a shared cache}.**
30610 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 .** ^(This routi
30620 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
30630 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 sables the shari
30640 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ng of the databa
30650 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 se cache.** and
30660 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 schema data stru
30670 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b ctures between [
30680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
30690 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e ion | connection
306a0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d s].** to the sam
306b0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 e database. Shar
306c0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 ing is enabled i
306d0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 f the argument i
306e0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 s true.** and di
306f0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 sabled if the ar
30700 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e gument is false.
30710 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 )^.**.** ^Cache
30720 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c sharing is enabl
30730 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ed and disabled
30740 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 for an entire pr
30750 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 ocess..** This i
30760 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 s a change as of
30770 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
30780 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 3.5.0. In prior
30790 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
307a0 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 te,.** sharing w
307b0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 as enabled or di
307c0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 sabled for each
307d0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c thread separatel
307e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 y..**.** ^(The c
307f0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 ache sharing mod
30800 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e e set by this in
30810 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 terface effects
30820 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
30830 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * calls to [sqli
30840 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
30850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
30860 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f , and [sqlite3_o
30870 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 pen16()]..** Exi
30880 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 sting database c
30890 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 onnections conti
308a0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 nue use the shar
308b0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 ing mode.** that
308c0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 was in effect a
308d0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 t the time they
308e0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a were opened.)^.*
308f0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
30900 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
30910 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
30920 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 d cache was enab
30930 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
30940 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
30950 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 An [error code
30960 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 ] is returned ot
30970 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a herwise.)^.**.**
30980 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69 ^Shared cache i
30990 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
309a0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 fault. But this
309b0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a might change in.
309c0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ** future releas
309d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 es of SQLite. A
309e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
309f0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 care about shar
30a00 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 ed.** cache sett
30a10 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 ing should set i
30a20 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a t explicitly..**
30a30 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b .** See Also: [
30a40 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 SQLite Shared-Ca
30a50 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 che Mode].*/.int
30a60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
30a70 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 shared_cache(int
30a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
30a90 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 EF: Attempt To F
30aa0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a ree Heap Memory.
30ab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
30ac0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
30ad0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 y() interface at
30ae0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e tempts to free N
30af0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 bytes.** of hea
30b00 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c p memory by deal
30b10 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 locating non-ess
30b20 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c ential memory al
30b30 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c locations.** hel
30b40 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 d by the databas
30b50 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d e library. Mem
30b60 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 ory used to cach
30b70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 e database.** pa
30b80 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 ges to improve p
30b90 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e erformance is an
30ba0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d example of non-
30bb0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
30bc0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 ..** ^sqlite3_re
30bd0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 lease_memory() r
30be0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
30bf0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 r of bytes actua
30c00 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 lly freed,.** wh
30c10 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 ich might be mor
30c20 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 e or less than t
30c30 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 he amount reques
30c40 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
30c50 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
30c60 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ory() routine is
30c70 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 a no-op returni
30c80 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 ng zero.** if SQ
30c90 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 Lite is not comp
30ca0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 iled with [SQLIT
30cb0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f E_ENABLE_MEMORY_
30cc0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a MANAGEMENT]..*/.
30cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
30ce0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
30cf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30d00 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 : Impose A Limit
30d10 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a On Heap Size.**
30d20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30d30 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
30d40 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 64() interface s
30d50 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 ets and/or queri
30d60 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c es the.** soft l
30d70 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 imit on the amou
30d80 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 nt of heap memor
30d90 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c y that may be al
30da0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 located by SQLit
30db0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 e..** ^SQLite st
30dc0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 rives to keep he
30dd0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a ap memory utiliz
30de0 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 ation below the
30df0 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d soft heap.** lim
30e00 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 it by reducing t
30e10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
30e20 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 es held in the p
30e30 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 age cache.** as
30e40 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 heap memory usag
30e50 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 es approaches th
30e60 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 e limit..** ^The
30e70 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
30e80 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 is "soft" becau
30e90 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 se even though S
30ea0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f QLite strives to
30eb0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 stay.** below t
30ec0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c he limit, it wil
30ed0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d l exceed the lim
30ee0 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 it rather than g
30ef0 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 enerate.** an [S
30f00 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 QLITE_NOMEM] err
30f10 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f or. In other wo
30f20 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 rds, the soft he
30f30 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 ap limit .** is
30f40 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a advisory only..*
30f50 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e *.** ^The return
30f60 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
30f70 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
30f80 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73 mit64() is the s
30f90 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f ize of.** the so
30fa0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 ft heap limit pr
30fb0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e ior to the call.
30fc0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 ^If the argume
30fd0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 nt N is negative
30fe0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e .** then no chan
30ff0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 ge is made to th
31000 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
31010 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 t. Hence, the c
31020 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f urrent.** size o
31030 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 f the soft heap
31040 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 limit can be det
31050 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b ermined by invok
31060 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
31070 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
31080 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 () with a negati
31090 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a ve argument..**.
310a0 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d ** ^If the argum
310b0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 ent N is zero th
310c0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 en the soft heap
310d0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c limit is disabl
310e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ed..**.** ^(The
310f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
31100 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 is not enforced
31110 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 in the current i
31120 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
31130 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 if one or more
31140 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e of following con
31150 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 ditions are true
31160 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
31170 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 <li> The soft he
31180 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 ap limit is set
31190 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e to zero..** <li>
311a0 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 Memory accounti
311b0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 ng is disabled u
311c0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 sing a combinati
311d0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 on of the.**
311e0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 [sqlite3_confi
311f0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
31200 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e G_MEMSTATUS],...
31210 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 ) start-time opt
31220 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ion and.**
31230 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 the [SQLITE_DEFA
31240 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 ULT_MEMSTATUS] c
31250 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
31260 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 on..** <li> An a
31270 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 lternative page
31280 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
31290 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 65 64 tion is specifed
312a0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b using.** [
312b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
312c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
312d0 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 CACHE],...)..**
312e0 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 <li> The page ca
312f0 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 che allocates fr
31300 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 om its own memor
31310 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a y pool supplied.
31320 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 ** by [sqli
31330 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
31340 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
31350 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 ACHE],...) rathe
31360 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 r than.** f
31370 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a rom the heap..**
31380 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 </ul>)^.**.** B
31390 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 eginning with SQ
313a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
313b0 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 .3, the soft hea
313c0 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 p limit is enfor
313d0 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 ced.** regardles
313e0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
313f0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f not the [SQLITE_
31400 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 ENABLE_MEMORY_MA
31410 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d NAGEMENT].** com
31420 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
31430 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 is invoked. Wi
31440 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c th [SQLITE_ENABL
31450 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d E_MEMORY_MANAGEM
31460 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 ENT],.** the sof
31470 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
31480 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 enforced on ever
31490 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
314a0 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a ion. Without.**
314b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
314c0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
314d0 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 T], the soft hea
314e0 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 p limit is only
314f0 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e enforced.** when
31500 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 memory is alloc
31510 61 74 65 64 20 62 79 20 74 68 65 20 70 61 67 65 ated by the page
31520 20 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 cache. Testing
31530 20 73 75 67 67 65 73 74 73 20 74 68 61 74 20 62 suggests that b
31540 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 ecause.** the pa
31550 67 65 20 63 61 63 68 65 20 69 73 20 74 68 65 20 ge cache is the
31560 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f predominate memo
31570 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 ry user in SQLit
31580 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 e, most.** appli
31590 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 cations will ach
315a0 69 65 76 65 20 61 64 65 71 75 61 74 65 20 73 6f ieve adequate so
315b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e ft heap limit en
315c0 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 forcement withou
315d0 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 t.** the use of
315e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
315f0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 EMORY_MANAGEMENT
31600 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 ]..**.** The cir
31610 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 cumstances under
31620 20 77 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 which SQLite wi
31630 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 ll enforce the s
31640 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d oft heap limit m
31650 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e ay.** changes in
31660 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
31670 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
31680 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
31690 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
316a0 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 imit64(sqlite3_i
316b0 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nt64 N);../*.**
316c0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
316d0 61 74 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c ated Soft Heap L
316e0 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a imit Interface.*
316f0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
31700 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64 65 70 ** This is a dep
31710 72 65 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 recated version
31720 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
31730 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 soft_heap_limit6
31740 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 4()].** interfac
31750 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 e. This routine
31760 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
31770 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
31780 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c atibility.** onl
31790 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c y. All new appl
317a0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
317b0 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 use the.** [sqli
317c0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
317d0 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 mit64()] interfa
317e0 63 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 ce rather than t
317f0 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 his one..*/.SQLI
31800 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
31810 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f id sqlite3_soft_
31820 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e heap_limit(int N
31830 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
31840 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 REF: Extract Met
31850 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f adata About A Co
31860 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a lumn Of A Table.
31870 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
31880 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 ine returns meta
31890 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 data about a spe
318a0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 cific column of
318b0 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 a specific.** da
318c0 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 tabase table acc
318d0 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 essible using th
318e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
318f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a ection] handle.*
31900 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 * passed as the
31910 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 first function a
31920 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
31930 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 The column is id
31940 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
31950 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e second, third an
31960 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
31970 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 ers to.** this f
31980 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 unction. ^The se
31990 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
319a0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d s either the nam
319b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
319c0 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e e.** (i.e. "main
319d0 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e ", "temp", or an
319e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
319f0 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 se) containing t
31a00 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 he specified.**
31a10 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e table or NULL. ^
31a20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 If it is NULL, t
31a30 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 hen all attached
31a40 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 databases are s
31a50 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 earched.** for t
31a60 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 he table using t
31a70 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
31a80 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 m used by the da
31a90 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f tabase engine to
31aa0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 .** resolve unqu
31ab0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 alified table re
31ac0 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 ferences..**.**
31ad0 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 ^The third and f
31ae0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
31af0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
31b00 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 n are the table
31b10 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 and column.** na
31b20 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 me of the desire
31b30 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 d column, respec
31b40 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 tively. Neither
31b50 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 of these paramet
31b60 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 ers.** may be NU
31b70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 LL..**.** ^Metad
31b80 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 ata is returned
31b90 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 by writing to th
31ba0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f e memory locatio
31bb0 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ns passed as the
31bc0 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 5th.** and subs
31bd0 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 equent parameter
31be0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 s to this functi
31bf0 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 on. ^Any of thes
31c00 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 e arguments may
31c10 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 be.** NULL, in w
31c20 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f hich case the co
31c30 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d rresponding elem
31c40 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 ent of metadata
31c50 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a is omitted..**.*
31c60 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e * ^(<blockquote>
31c70 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
31c80 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
31c90 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 h> Parameter <th
31ca0 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 > Output<br>Type
31cb0 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 <th> Descripti
31cc0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
31cd0 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 > 5th <td> const
31ce0 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 char* <td> Data
31cf0 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 type.** <tr><td
31d00 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 > 6th <td> const
31d10 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 char* <td> Name
31d20 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c of default coll
31d30 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a ation sequence.*
31d40 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c * <tr><td> 7th <
31d50 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 td> int
31d60 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c <td> True if col
31d70 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 umn has a NOT NU
31d80 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a LL constraint.**
31d90 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 <tr><td> 8th <t
31da0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
31db0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
31dc0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 mn is part of th
31dd0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a e PRIMARY KEY.**
31de0 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 <tr><td> 9th <t
31df0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
31e00 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
31e10 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 mn is [AUTOINCRE
31e20 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 MENT].** </table
31e30 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
31e40 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
31e50 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 memory pointed t
31e60 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 o by the charact
31e70 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 er pointers retu
31e80 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 rned for the.**
31e90 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 declaration type
31ea0 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 and collation s
31eb0 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 equence is valid
31ec0 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 only until the
31ed0 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 next.** call to
31ee0 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 any SQLite API f
31ef0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
31f00 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 If the specified
31f10 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c table is actual
31f20 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 ly a view, an [e
31f30 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
31f40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 turned..**.** ^I
31f50 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 f the specified
31f60 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 column is "rowid
31f70 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f ", "oid" or "_ro
31f80 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 wid_" and an.**
31f90 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
31fa0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 KEY] column has
31fb0 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 been explicitly
31fc0 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 declared, then
31fd0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 the output.** pa
31fe0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
31ff0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 for the explici
32000 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
32010 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 umn. ^(If there
32020 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 is no.** explici
32030 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e tly declared [IN
32040 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
32050 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 Y] column, then
32060 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 the output.** pa
32070 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
32080 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
32090 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
320a0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 data type: "INTE
320b0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c GER".** coll
320c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 ation sequence:
320d0 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 "BINARY".**
320e0 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 not null: 0.**
320f0 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 primary key:
32100 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 1.** auto in
32110 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f crement: 0.** </
32120 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 pre>)^.**.** ^(T
32130 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 his function may
32140 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 load one or mor
32150 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 e schemas from d
32160 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 atabase files. I
32170 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 f an.** error oc
32180 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 curs during this
32190 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 process, or if
321a0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 the requested ta
321b0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a ble or column.**
321c0 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 cannot be found
321d0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 , an [error code
321e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
321f0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 d an error messa
32200 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 ge left.** in th
32210 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
32220 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 ection] (to be r
32230 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 etrieved using s
32240 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 qlite3_errmsg())
32250 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 .)^.**.** ^This
32260 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 API is only avai
32270 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
32280 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
32290 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
322a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
322b0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
322c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
322d0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a bol defined..*/.
322e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c int sqlite3_tabl
322f0 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 e_column_metadat
32300 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 a(. sqlite3 *db
32310 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
32320 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 /* Connection h
32330 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
32340 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 char *zDbName,
32350 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
32360 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 se name or NULL
32370 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
32380 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 *zTableName,
32390 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a /* Table name *
323a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
323b0 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 zColumnName,
323c0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a /* Column name *
323d0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a /. char const *
323e0 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 *pzDataType,
323f0 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 /* OUTPUT: Decla
32400 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f red data type */
32410 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a . char const **
32420 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f pzCollSeq, /
32430 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 * OUTPUT: Collat
32440 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ion sequence nam
32450 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 e */. int *pNot
32460 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 Null,
32470 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 /* OUTPUT: Tr
32480 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 ue if NOT NULL c
32490 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 onstraint exists
324a0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d */. int *pPrim
324b0 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 aryKey,
324c0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
324d0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 e if column part
324e0 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 of PK */. int
324f0 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 *pAutoinc
32500 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
32510 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
32520 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d n is auto-increm
32530 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ent */.);../*.**
32540 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 CAPI3REF: Load
32550 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a An Extension.**.
32560 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 ** ^This interfa
32570 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 ce loads an SQLi
32580 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 te extension lib
32590 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 rary from the na
325a0 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 med file..**.**
325b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 ^The sqlite3_loa
325c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
325d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
325e0 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 to load an.** S
325f0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
32600 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 library containe
32610 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 d in the file zF
32620 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ile..**.** ^The
32630 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a entry point is z
32640 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 Proc..** ^zProc
32650 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 may be 0, in whi
32660 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 ch case the name
32670 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f of the entry po
32680 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 int.** defaults
32690 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 to "sqlite3_exte
326a0 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 nsion_init"..**
326b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 ^The sqlite3_loa
326c0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
326d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
326e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f ** [SQLITE_OK] o
326f0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 n success and [S
32700 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
32710 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 something goes w
32720 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 rong..** ^If an
32730 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 error occurs and
32740 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 pzErrMsg is not
32750 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 0, then the.**
32760 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
32770 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 tension()] inter
32780 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d face shall attem
32790 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 pt to.** fill *p
327a0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 zErrMsg with err
327b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
327c0 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 stored in memory
327d0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f .** obtained fro
327e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
327f0 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e c()]. The callin
32800 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 g function.** sh
32810 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d ould free this m
32820 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 emory by calling
32830 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
32840 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 ]..**.** ^Extens
32850 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 ion loading must
32860 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e be enabled usin
32870 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e g.** [sqlite3_en
32880 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
32890 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 ion()] prior to
328a0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 calling this API
328b0 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 ,.** otherwise a
328c0 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 n error will be
328d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
328e0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f See also the [lo
328f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 ad_extension() S
32900 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f QL function]..*/
32910 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 .int sqlite3_loa
32920 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 d_extension(. s
32930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
32940 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 /* Load the
32950 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 extension into
32960 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f this database co
32970 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f nnection */. co
32980 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
32990 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
329a0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 he shared librar
329b0 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 y containing ext
329c0 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ension */. cons
329d0 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 t char *zProc,
329e0 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 /* Entry point
329f0 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 . Derived from
32a00 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 zFile if 0 */.
32a10 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 char **pzErrMsg
32a20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 /* Put err
32a30 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 or message here
32a40 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a if not 0 */.);..
32a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32a60 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
32a70 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 e Extension Load
32a80 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 ing.**.** ^So as
32a90 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 not to open sec
32aa0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f urity holes in o
32ab0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e lder application
32ac0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e s that are.** un
32ad0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c prepared to deal
32ae0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 with extension
32af0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 loading, and as
32b00 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 a means of disab
32b10 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f ling.** extensio
32b20 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 n loading while
32b30 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d evaluating user-
32b40 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 entered SQL, the
32b50 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a following API.*
32b60 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f * is provided to
32b70 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 turn the [sqlit
32b80 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
32b90 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f n()] mechanism o
32ba0 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a n and off..**.**
32bb0 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 ^Extension load
32bc0 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 ing is off by de
32bd0 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 fault. See ticke
32be0 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c t #1863..** ^Cal
32bf0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e l the sqlite3_en
32c00 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
32c10 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 ion() routine wi
32c20 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 th onoff==1.** t
32c30 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e o turn extension
32c40 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 loading on and
32c50 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f call it with ono
32c60 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a ff==0 to turn.**
32c70 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 it back off aga
32c80 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 in..*/.int sqlit
32c90 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
32ca0 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 xtension(sqlite3
32cb0 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 *db, int onoff)
32cc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
32cd0 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 F: Automatically
32ce0 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 Load Statically
32cf0 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f Linked Extensio
32d00 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 ns.**.** ^This i
32d10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
32d20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 the xEntryPoint(
32d30 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 ) function to be
32d40 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 invoked for.**
32d50 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 each new [databa
32d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
32d70 68 61 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 hat is created.
32d80 20 54 68 65 20 69 64 65 61 20 68 65 72 65 20 69 The idea here i
32d90 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 s that.** xEntry
32da0 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 Point() is the e
32db0 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 ntry point for a
32dc0 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b statically link
32dd0 65 64 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 ed SQLite extens
32de0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 ion.** that is t
32df0 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c o be automatical
32e00 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 ly loaded into a
32e10 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 ll new database
32e20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a connections..**.
32e30 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 ** ^(Even though
32e40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 the function pr
32e50 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 ototype shows th
32e60 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 at xEntryPoint()
32e70 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 takes.** no arg
32e80 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 uments and retur
32e90 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 ns void, SQLite
32ea0 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f invokes xEntryPo
32eb0 69 6e 74 28 29 20 77 69 74 68 20 74 68 72 65 65 int() with three
32ec0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e .** arguments an
32ed0 64 20 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e d expects and in
32ee0 74 65 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 teger result as
32ef0 69 66 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 if the signature
32f00 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 of the.** entry
32f10 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 point where as
32f20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
32f30 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
32f40 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 .** int
32f50 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 xEntryPoint(.**
32f60 26 6e 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 sqlite
32f70 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 3 *db,.**
32f80 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a const char *
32f90 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e *pzErrMsg,.** &n
32fa0 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 bsp; const st
32fb0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 ruct sqlite3_api
32fc0 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e _routines *pThun
32fd0 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a k.** );.
32fe0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
32ff0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 quote>)^.**.** I
33000 66 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e f the xEntryPoin
33010 74 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e t routine encoun
33020 74 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 ters an error, i
33030 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 t should make *p
33040 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 zErrMsg.** point
33050 20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 to an appropria
33060 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 te error message
33070 20 28 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 (obtained from
33080 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
33090 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 ()]).** and retu
330a0 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 rn an appropriat
330b0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 e [error code].
330c0 20 5e 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 ^SQLite ensures
330d0 20 74 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a that *pzErrMsg.
330e0 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 ** is NULL befor
330f0 65 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 e calling the xE
33100 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 ntryPoint(). ^S
33110 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
33120 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 e.** [sqlite3_fr
33130 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d ee()] on *pzErrM
33140 73 67 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 sg after xEntryP
33150 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 oint() returns.
33160 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 ^If any.** xEnt
33170 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e ryPoint() return
33180 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 s an error, the
33190 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
331a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
331b0 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 6()],.** or [sql
331c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
331d0 63 61 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b call that provok
331e0 65 64 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 ed the xEntryPoi
331f0 6e 74 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a nt() will fail..
33200 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
33210 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
33220 6e 73 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e nsion(X) with an
33230 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 entry point X t
33240 68 61 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a hat is already.*
33250 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 * on the list of
33260 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e automatic exten
33270 73 69 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c sions is a harml
33280 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 ess no-op. ^No e
33290 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 ntry point.** wi
332a0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 ll be called mor
332b0 65 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 e than once for
332c0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
332d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 nnection that is
332e0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 opened..**.** S
332f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
33300 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 3_reset_auto_ext
33310 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e ension()]..*/.in
33320 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 t sqlite3_auto_e
33330 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a xtension(void (*
33340 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 xEntryPoint)(voi
33350 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d));../*.** CAPI
33360 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 3REF: Reset Auto
33370 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 matic Extension
33380 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 Loading.**.** ^T
33390 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 his interface di
333a0 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d sables all autom
333b0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 atic extensions
333c0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 previously.** re
333d0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b gistered using [
333e0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 sqlite3_auto_ext
333f0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f ension()]..*/.vo
33400 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 id sqlite3_reset
33410 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
33420 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 void);../*.** Th
33430 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
33440 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
33450 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 mechanism is cu
33460 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
33470 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
33480 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
33490 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
334a0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
334b0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
334c0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
334d0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
334e0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
334f0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
33500 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
33510 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
33520 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 mechanism stabi
33530 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
33540 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
33550 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
33560 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
33570 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
33580 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
33590 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 .*/../*.** Struc
335a0 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 tures used by th
335b0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
335c0 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 interface.*/.typ
335d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
335e0 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 te3_vtab sqlite3
335f0 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 _vtab;.typedef s
33600 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
33610 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 dex_info sqlite3
33620 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 _index_info;.typ
33630 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
33640 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
33650 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
33660 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 sor;.typedef str
33670 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
33680 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c le sqlite3_modul
33690 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
336a0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
336b0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 e Object.** KEYW
336c0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f ORDS: sqlite3_mo
336d0 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 dule {virtual ta
336e0 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a ble module}.**.*
336f0 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 * This structure
33700 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c , sometimes call
33710 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 ed a a "virtual
33720 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a table module", .
33730 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ** defines the i
33740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
33750 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
33760 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 es]. .** This s
33770 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 tructure consist
33780 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 s mostly of meth
33790 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 ods for the modu
337a0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 le..**.** ^A vir
337b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
337c0 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 e is created by
337d0 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 filling in a per
337e0 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 sistent.** insta
337f0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
33800 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e cture and passin
33810 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 g a pointer to t
33820 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 hat instance.**
33830 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
33840 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 te_module()] or
33850 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33860 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a module_v2()]..**
33870 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 ^The registrati
33880 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 on remains valid
33890 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 until it is rep
338a0 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 laced by a diffe
338b0 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f rent.** module o
338c0 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 r until the [dat
338d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
338e0 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 ] closes. The c
338f0 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 ontent.** of thi
33900 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 s structure must
33910 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c not change whil
33920 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 e it is register
33930 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 ed with.** any d
33940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
33950 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 on..*/.struct sq
33960 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 lite3_module {.
33970 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
33980 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 int (*xCreate)(
33990 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
339a0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
339b0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
339c0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
339d0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
339e0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
339f0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
33a00 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 r**);. int (*xC
33a10 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a onnect)(sqlite3*
33a20 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
33a30 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
33a40 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
33a50 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
33a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
33a70 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
33a80 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
33a90 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 int (*xBestIndex
33aa0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
33ab0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 pVTab, sqlite3_i
33ac0 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 ndex_info*);. i
33ad0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 nt (*xDisconnect
33ae0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
33af0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
33b00 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 xDestroy)(sqlite
33b10 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
33b20 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
33b30 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
33b40 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 ab, sqlite3_vtab
33b50 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 _cursor **ppCurs
33b60 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c or);. int (*xCl
33b70 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ose)(sqlite3_vta
33b80 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
33b90 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c t (*xFilter)(sql
33ba0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
33bb0 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 *, int idxNum, c
33bc0 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 onst char *idxSt
33bd0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 r,.
33be0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c int argc, sql
33bf0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 ite3_value **arg
33c00 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 v);. int (*xNex
33c10 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f t)(sqlite3_vtab_
33c20 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
33c30 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f (*xEof)(sqlite3_
33c40 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
33c50 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 int (*xColumn)(
33c60 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
33c70 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f sor*, sqlite3_co
33c80 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 ntext*, int);.
33c90 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 int (*xRowid)(sq
33ca0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
33cb0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 r*, sqlite3_int6
33cc0 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 4 *pRowid);. in
33cd0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c t (*xUpdate)(sql
33ce0 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 ite3_vtab *, int
33cf0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 , sqlite3_value
33d00 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 **, sqlite3_int6
33d10 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 4 *);. int (*xB
33d20 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 egin)(sqlite3_vt
33d30 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
33d40 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 t (*xSync)(sqlit
33d50 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
33d60 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 . int (*xCommit
33d70 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
33d80 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
33d90 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 xRollback)(sqlit
33da0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
33db0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 . int (*xFindFu
33dc0 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f nction)(sqlite3_
33dd0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 vtab *pVtab, int
33de0 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 nArg, const cha
33df0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 r *zName,.
33e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
33e10 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 void (**pxFunc)
33e20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33e30 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
33e40 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 lue**),.
33e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
33e60 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 oid **ppArg);.
33e70 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 int (*xRename)(s
33e80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
33e90 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ab, const char *
33ea0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a zNew);.};../*.**
33eb0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
33ec0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e al Table Indexin
33ed0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a g Information.**
33ee0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
33ef0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a e3_index_info.**
33f00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
33f10 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 index_info struc
33f20 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 ture and its sub
33f30 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 structures is us
33f40 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 ed as part.** of
33f50 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 the [virtual ta
33f60 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74 ble] interface t
33f70 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d o.** pass inform
33f80 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 ation into and r
33f90 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 eceive the reply
33fa0 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 from the [xBest
33fb0 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 Index].** method
33fc0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 of a [virtual t
33fd0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 able module]. T
33fe0 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 he fields under
33ff0 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 **Inputs** are t
34000 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 he.** inputs to
34010 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 xBestIndex and a
34020 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 re read-only. x
34030 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 BestIndex insert
34040 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 s its.** results
34050 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 into the **Outp
34060 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a uts** fields..**
34070 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 .** ^(The aConst
34080 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 raint[] array re
34090 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 cords WHERE clau
340a0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f se constraints o
340b0 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a f the form:.**.*
340c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f * <blockquote>co
340d0 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c lumn OP expr</bl
340e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
340f0 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 where OP is =, &
34100 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b lt;, <=, >
34110 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e , or >=.)^ ^
34120 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 (The particular
34130 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 operator is.** s
34140 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 tored in aConstr
34150 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 aint[].op using
34160 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 one of the.** [S
34170 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
34180 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 TRAINT_EQ | SQLI
34190 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
341a0 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a INT_ values].)^.
341b0 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f ** ^(The index o
341c0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
341d0 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f stored in.** aCo
341e0 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 nstraint[].iColu
341f0 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 mn.)^ ^(aConstr
34200 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 aint[].usable is
34210 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 TRUE if the.**
34220 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 expr on the righ
34230 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 t-hand side can
34240 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e be evaluated (an
34250 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 d thus the const
34260 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 raint.** is usab
34270 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 le) and false if
34280 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a it cannot.)^.**
34290 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a .** ^The optimiz
342a0 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 er automatically
342b0 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f inverts terms o
342c0 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 f the form "expr
342d0 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 OP column".** a
342e0 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 nd makes other s
342f0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 implifications t
34300 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 o the WHERE clau
34310 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 se in an attempt
34320 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 to.** get as ma
34330 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ny WHERE clause
34340 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 terms into the f
34350 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 orm shown above
34360 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 as possible..**
34370 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 ^The aConstraint
34380 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 [] array only re
34390 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 ports WHERE clau
343a0 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 se terms that ar
343b0 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f e.** relevant to
343c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
343d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 virtual table be
343e0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a ing queried..**.
343f0 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 ** ^Information
34400 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 about the ORDER
34410 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f BY clause is sto
34420 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b red in aOrderBy[
34430 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d ]..** ^Each term
34440 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 of aOrderBy rec
34450 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 ords a column of
34460 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
34470 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ause..**.** The
34480 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 [xBestIndex] met
34490 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 hod must fill aC
344a0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
344b0 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f with informatio
344c0 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 n.** about what
344d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 parameters to pa
344e0 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 ss to xFilter.
344f0 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 ^If argvIndex>0
34500 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 then.** the righ
34510 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 t-hand side of t
34520 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
34530 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 aConstraint[] i
34540 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 s evaluated.** a
34550 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 nd becomes the a
34560 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 rgvIndex-th entr
34570 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 y in argv. ^(If
34580 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 aConstraintUsag
34590 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 e[].omit.** is t
345a0 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f rue, then the co
345b0 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 nstraint is assu
345c0 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 med to be fully
345d0 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a handled by the.*
345e0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * virtual table
345f0 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b and is not check
34600 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 ed again by SQLi
34610 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te.)^.**.** ^The
34620 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 idxNum and idxP
34630 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 tr values are re
34640 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 corded and passe
34650 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 d into the.** [x
34660 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a Filter] method..
34670 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 ** ^[sqlite3_fre
34680 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 e()] is used to
34690 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 free idxPtr if a
346a0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 nd only if.** ne
346b0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 edToFreeIdxPtr i
346c0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s true..**.** ^T
346d0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
346e0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
346f0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 tput from [xFilt
34700 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c er]/[xNext] will
34710 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 occur in.** the
34720 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 correct order t
34730 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 o satisfy the OR
34740 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f DER BY clause so
34750 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 that no separat
34760 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 e.** sorting ste
34770 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a p is required..*
34780 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 *.** ^The estima
34790 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 tedCost value is
347a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
347b0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e the cost of doin
347c0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 g the.** particu
347d0 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 lar lookup. A f
347e0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 ull scan of a ta
347f0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 ble with N entri
34800 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a es should have.*
34810 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 * a cost of N.
34820 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 A binary search
34830 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 of a table of N
34840 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 entries should h
34850 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 ave a.** cost of
34860 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c approximately l
34870 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 og(N)..*/.struct
34880 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
34890 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 nfo {. /* Input
348a0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 s */. int nCons
348b0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 traint;
348c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 /* Number of e
348d0 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 ntries in aConst
348e0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 raint */. struc
348f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
34900 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 constraint {.
34910 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
34920 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
34930 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 olumn on left-ha
34940 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 nd side of const
34950 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e raint */. un
34960 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 signed char op;
34970 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 /* Const
34980 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a raint operator *
34990 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
349a0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 char usable;
349b0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 /* True if this
349c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 constraint is u
349d0 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e sable */. in
349e0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 t iTermOffset;
349f0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 /* Used
34a00 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 internally - xBe
34a10 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 stIndex should i
34a20 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 gnore */. } *aC
34a30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 onstraint;
34a40 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f /* Table o
34a50 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 f WHERE clause c
34a60 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 onstraints */.
34a70 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 int nOrderBy;
34a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
34a90 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
34aa0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
34ab0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 ause */. struct
34ac0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f sqlite3_index_o
34ad0 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e rderby {. in
34ae0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 t iColumn;
34af0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d /* Colum
34b00 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 n number */.
34b10 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 unsigned char d
34b20 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 esc; /* Tr
34b30 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 ue for DESC. Fa
34b40 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a lse for ASC. */.
34b50 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 } *aOrderBy;
34b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
34b70 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 The ORDER BY cla
34b80 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 use */. /* Outp
34b90 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 uts */. struct
34ba0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f sqlite3_index_co
34bb0 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b nstraint_usage {
34bc0 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 . int argvInd
34bd0 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a ex; /*
34be0 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 if >0, constrai
34bf0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 nt is part of ar
34c00 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f gv to xFilter */
34c10 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 . unsigned ch
34c20 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a ar omit; /*
34c30 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 Do not code a t
34c40 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e est for this con
34c50 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a straint */. } *
34c60 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
34c70 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 ;. int idxNum;
34c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
34c90 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f * Number used to
34ca0 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e identify the in
34cb0 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 dex */. char *i
34cc0 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 dxStr;
34cd0 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 /* String, p
34ce0 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 ossibly obtained
34cf0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
34d00 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 lloc */. int ne
34d10 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 edToFreeIdxStr;
34d20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 /* Free idx
34d30 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 Str using sqlite
34d40 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 3_free() if true
34d50 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 */. int orderB
34d60 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 yConsumed;
34d70 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 /* True if outp
34d80 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 ut is already or
34d90 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c dered */. doubl
34da0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b e estimatedCost;
34db0 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 /* Estimat
34dc0 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 ed cost of using
34dd0 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d this index */.}
34de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34df0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 F: Virtual Table
34e00 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 Constraint Oper
34e10 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a ator Codes.**.**
34e20 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64 65 These macros de
34e30 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 fined the allowe
34e40 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 d values for the
34e50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 .** [sqlite3_ind
34e60 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 ex_info].aConstr
34e70 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e aint[].op field.
34e80 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65 70 Each value rep
34e90 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 resents.** an op
34ea0 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20 70 erator that is p
34eb0 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 art of a constra
34ec0 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65 20 int term in the
34ed0 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 0a wHERE clause of.
34ee0 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74 20 ** a query that
34ef0 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c 20 uses a [virtual
34f00 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 table]..*/.#defi
34f10 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
34f20 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 CONSTRAINT_EQ
34f30 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
34f40 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
34f50 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 NT_GT 4.#defi
34f60 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
34f70 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 CONSTRAINT_LE
34f80 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
34f90 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
34fa0 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 NT_LT 16.#def
34fb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
34fc0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 _CONSTRAINT_GE
34fd0 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 32.#define SQL
34fe0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
34ff0 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f AINT_MATCH 64../
35000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
35010 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 egister A Virtua
35020 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e l Table Implemen
35030 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tation.**.** ^Th
35040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
35050 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
35060 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c r a new [virtual
35070 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e table module] n
35080 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 ame..** ^Module
35090 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 names must be re
350a0 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a gistered before.
350b0 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 ** creating a ne
350c0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 w [virtual table
350d0 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 ] using the modu
350e0 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 le and before us
350f0 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 ing a.** preexis
35100 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 ting [virtual ta
35110 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 ble] for the mod
35120 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ule..**.** ^The
35130 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 module name is r
35140 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 egistered on the
35150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
35160 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 ction] specified
35170 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
35180 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 parameter. ^Th
35190 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f e name of the mo
351a0 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79 dule is given by
351b0 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 the .** second
351c0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 parameter. ^The
351d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
351e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
351f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
35200 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 tation of the [v
35210 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
35220 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 ule]. ^The fou
35230 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rth.** parameter
35240 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
35250 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 client data poi
35260 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
35270 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 sed through.** i
35280 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 nto the [xCreate
35290 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d ] and [xConnect]
352a0 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 methods of the
352b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
352c0 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e dule.** when a n
352d0 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ew virtual table
352e0 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 is be being cre
352f0 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 ated or reinitia
35300 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lized..**.** ^Th
35310 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
35320 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 _module_v2() int
35330 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69 66 erface has a fif
35340 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 th parameter whi
35350 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
35360 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 er to a destruct
35370 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65 or for the pClie
35380 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 ntData. ^SQLite
35390 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 will.** invoke
353a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 the destructor f
353b0 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 unction (if it i
353c0 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e s not NULL) when
353d0 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f SQLite.** no lo
353e0 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 nger needs the p
353f0 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 ClientData point
35400 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 er. ^The destru
35410 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a ctor will also.*
35420 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 66 20 * be invoked if
35430 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 the call to sqli
35440 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
35450 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a e_v2() fails..**
35460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 ^The sqlite3_cr
35470 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a eate_module().**
35480 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 interface is eq
35490 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 uivalent to sqli
354a0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
354b0 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 e_v2() with a NU
354c0 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 LL.** destructor
354d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
354e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a _create_module(.
354f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
35500 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
35510 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f SQLite connectio
35520 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f n to register mo
35530 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 dule with */. c
35540 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
35550 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d , /* Nam
35560 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 e of the module
35570 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 */. const sqlit
35580 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 e3_module *p,
35590 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 /* Methods for t
355a0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 he module */. v
355b0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 oid *pClientData
355c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 /* Cli
355d0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 ent data for xCr
355e0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f eate/xConnect */
355f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
35600 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
35610 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
35620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
35630 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 * SQLite connect
35640 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 ion to register
35650 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 module with */.
35660 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
35670 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e me, /* N
35680 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
35690 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c e */. const sql
356a0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 ite3_module *p,
356b0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
356c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
356d0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 void *pClientDa
356e0 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 ta, /* C
356f0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 lient data for x
35700 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 Create/xConnect
35710 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 */. void(*xDest
35720 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 roy)(void*)
35730 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 /* Module destru
35740 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f ctor function */
35750 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
35760 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
35770 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 le Instance Obje
35780 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
35790 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a sqlite3_vtab.**.
357a0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 ** Every [virtua
357b0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 l table module]
357c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
357d0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a ses a subclass.*
357e0 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 * of this object
357f0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 to describe a p
35800 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e articular instan
35810 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 ce.** of the [vi
35820 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 rtual table]. E
35830 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c ach subclass wil
35840 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 l.** be tailored
35850 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
35860 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f needs of the mo
35870 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
35880 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 ion..** The purp
35890 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 ose of this supe
358a0 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 rclass is to def
358b0 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c ine certain fiel
358c0 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 ds that are.** c
358d0 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 ommon to all mod
358e0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
358f0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 ons..**.** ^Virt
35900 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f ual tables metho
35910 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 ds can set an er
35920 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 ror message by a
35930 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 ssigning a.** st
35940 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 ring obtained fr
35950 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 om [sqlite3_mpri
35960 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 ntf()] to zErrMs
35970 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 g. The method s
35980 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 hould.** take ca
35990 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f re that any prio
359a0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 r string is free
359b0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b d by a call to [
359c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
359d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 ** prior to assi
359e0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 gning a new stri
359f0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 ng to zErrMsg.
35a00 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 ^After the error
35a10 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 message.** is d
35a20 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 elivered up to t
35a30 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 he client applic
35a40 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e ation, the strin
35a50 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 g will be automa
35a60 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 tically.** freed
35a70 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 by sqlite3_free
35a80 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d () and the zErrM
35a90 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 sg field will be
35aa0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 zeroed..*/.stru
35ab0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 ct sqlite3_vtab
35ac0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 {. const sqlite
35ad0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 3_module *pModul
35ae0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c e; /* The modul
35af0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 e for this virtu
35b00 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e al table */. in
35b10 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 t nRef;
35b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
35b30 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 NO LONGER USED
35b40 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d */. char *zErrM
35b50 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 sg;
35b60 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 /* Error me
35b70 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 ssage from sqlit
35b80 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a e3_mprintf() */.
35b90 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 /* Virtual tab
35ba0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
35bb0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c ns will typicall
35bc0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c y add additional
35bd0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f fields */.};../
35be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
35bf0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 irtual Table Cur
35c00 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 sor Object.** KE
35c10 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
35c20 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 vtab_cursor {vir
35c30 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f tual table curso
35c40 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b r}.**.** Every [
35c50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
35c60 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 dule] implementa
35c70 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 tion uses a subc
35c80 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 lass of the.** f
35c90 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
35ca0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 re to describe c
35cb0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e ursors that poin
35cc0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 t into the.** [v
35cd0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e irtual table] an
35ce0 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f d are used.** to
35cf0 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 loop through th
35d00 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e e virtual table.
35d10 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 Cursors are cr
35d20 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a eated using the.
35d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 ** [sqlite3_modu
35d40 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e le.xOpen | xOpen
35d50 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 ] method of the
35d60 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 module and are d
35d70 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 estroyed.** by t
35d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 he [sqlite3_modu
35d90 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f le.xClose | xClo
35da0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 se] method. Cur
35db0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a sors are used.**
35dc0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 by the [xFilter
35dd0 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f ], [xNext], [xEo
35de0 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 f], [xColumn], a
35df0 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 nd [xRowid] meth
35e00 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f ods.** of the mo
35e10 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 dule. Each modu
35e20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
35e30 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a n will define.**
35e40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
35e50 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 a cursor structu
35e60 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f re to suit its o
35e70 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 wn needs..**.**
35e80 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 This superclass
35e90 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 exists in order
35ea0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 to define fields
35eb0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 of the cursor t
35ec0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f hat.** are commo
35ed0 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 n to all impleme
35ee0 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 ntations..*/.str
35ef0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
35f00 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 _cursor {. sqli
35f10 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b te3_vtab *pVtab;
35f20 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c /* Virtual
35f30 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 table of this c
35f40 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 ursor */. /* Vi
35f50 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
35f60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
35f70 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 typically add a
35f80 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
35f90 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
35fa0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 PI3REF: Declare
35fb0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 The Schema Of A
35fc0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a Virtual Table.**
35fd0 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 .** ^The [xCreat
35fe0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 e] and [xConnect
35ff0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a ] methods of a.*
36000 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 * [virtual table
36010 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 module] call th
36020 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 is interface.**
36030 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 to declare the f
36040 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 ormat (the names
36050 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f and datatypes o
36060 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f f the columns) o
36070 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c f.** the virtual
36080 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 tables they imp
36090 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 lement..*/.int s
360a0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 qlite3_declare_v
360b0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f tab(sqlite3*, co
360c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b nst char *zSQL);
360d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
360e0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e : Overload A Fun
360f0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 ction For A Virt
36100 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 ual Table.**.**
36110 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 ^(Virtual tables
36120 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 can provide alt
36130 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 ernative impleme
36140 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 ntations of func
36150 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 tions.** using t
36160 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f he [xFindFunctio
36170 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 n] method of the
36180 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
36190 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 module]. .** Bu
361a0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
361b0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
361c0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
361d0 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
361e0 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a e overloaded.)^.
361f0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 **.** ^(This API
36200 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c makes sure a gl
36210 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 obal version of
36220 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 a function with
36230 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
36240 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 name and number
36250 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 of parameters ex
36260 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 ists. If no suc
36270 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 h function exist
36280 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 s.** before this
36290 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 API is called,
362a0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 a new function i
362b0 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 s created.)^ ^T
362c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
362d0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 n.** of the new
362e0 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 function always
362f0 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 causes an except
36300 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e ion to be thrown
36310 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 . So.** the new
36320 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 function is not
36330 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 good for anythi
36340 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 ng by itself. I
36350 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f ts only.** purpo
36360 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c se is to be a pl
36370 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 aceholder functi
36380 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f on that can be o
36390 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 verloaded.** by
363a0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
363b0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
363c0 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 3_overload_funct
363d0 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f ion(sqlite3*, co
363e0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e nst char *zFuncN
363f0 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a ame, int nArg);.
36400 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 ./*.** The inter
36410 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 face to the virt
36420 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e ual-table mechan
36430 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 ism defined abov
36440 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f e (back up.** to
36450 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 a comment remar
36460 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f kably similar to
36470 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 this one) is cu
36480 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
36490 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
364a0 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
364b0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
364c0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
364d0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
364e0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
364f0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
36500 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
36510 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
36520 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
36530 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
36540 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 mechanism stabi
36550 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
36560 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
36570 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
36580 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
36590 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
365a0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
365b0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .*/../*.** CAPI3
365c0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f REF: A Handle To
365d0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a An Open BLOB.**
365e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 KEYWORDS: {BLOB
365f0 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 handle} {BLOB h
36600 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e andles}.**.** An
36610 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
36620 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
36630 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 nts an open BLOB
36640 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 on which.** [sq
36650 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
36660 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
36670 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 OB I/O] can be p
36680 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 erformed..** ^Ob
36690 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 jects of this ty
366a0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 pe are created b
366b0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
366c0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 open()].** and d
366d0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
366e0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
366f0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c )]..** ^The [sql
36700 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 ite3_blob_read()
36710 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
36720 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 lob_write()] int
36730 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 erfaces.** can b
36740 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f e used to read o
36750 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 r write small su
36760 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 bsections of the
36770 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b BLOB..** ^The [
36780 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 sqlite3_blob_byt
36790 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 es()] interface
367a0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
367b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 of the BLOB in
367c0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 bytes..*/.typede
367d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
367e0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c _blob sqlite3_bl
367f0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ob;../*.** CAPI3
36800 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 REF: Open A BLOB
36810 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c For Incremental
36820 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 I/O.**.** ^(Thi
36830 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 s interfaces ope
36840 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ns a [BLOB handl
36850 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 e | handle] to t
36860 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a he BLOB located.
36870 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 ** in row iRow,
36880 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 column zColumn,
36890 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 table zTable in
368a0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a database zDb;.**
368b0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c in other words,
368c0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 the same BLOB t
368d0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c hat would be sel
368e0 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 ected by:.**.**
368f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c <pre>.** SEL
36900 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d ECT zColumn FROM
36910 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 zDb.zTable WHER
36920 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 E [rowid] = iRow
36930 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a ;.** </pre>)^.**
36940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 .** ^If the flag
36950 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e s parameter is n
36960 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 on-zero, then th
36970 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 e BLOB is opened
36980 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 for read.** and
36990 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e write access. ^
369a0 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 If it is zero, t
369b0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 he BLOB is opene
369c0 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 d for read acces
369d0 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 s..** ^It is not
369e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 possible to ope
369f0 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 n a column that
36a00 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e is part of an in
36a10 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a dex or primary .
36a20 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 ** key for writi
36a30 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e ng. ^If [foreign
36a40 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
36a50 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 ] are enabled, i
36a60 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 t is .** not pos
36a70 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 sible to open a
36a80 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 column that is p
36a90 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 art of a [child
36aa0 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 key] for writing
36ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
36ac0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
36ad0 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 name is not the
36ae0 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f filename that co
36af0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 ntains.** the da
36b00 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 tabase but rathe
36b10 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e r the symbolic n
36b20 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
36b30 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 ase that.** appe
36b40 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 ars after the AS
36b50 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 keyword when th
36b60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f e database is co
36b70 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 nnected using [A
36b80 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 TTACH]..** ^For
36b90 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
36ba0 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 e file, the data
36bb0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 base name is "ma
36bc0 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d in"..** ^For TEM
36bd0 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 P tables, the da
36be0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 tabase name is "
36bf0 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f temp"..**.** ^(O
36c00 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 n success, [SQLI
36c10 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
36c20 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b ed and the new [
36c30 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 BLOB handle] is
36c40 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 written.** to *p
36c50 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 pBlob. Otherwise
36c60 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
36c70 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
36c80 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a *ppBlob is set.
36c90 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 ** to be a null
36ca0 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 pointer.)^.** ^T
36cb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 his function set
36cc0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
36cd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f connection] erro
36ce0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
36cf0 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 ge.** accessible
36d00 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 via [sqlite3_er
36d10 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 rcode()] and [sq
36d20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
36d30 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 and related.** f
36d40 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 unctions. ^Note
36d50 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 that the *ppBlob
36d60 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 variable is alw
36d70 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 ays initialized
36d80 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 in a.** way that
36d90 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 makes it safe t
36da0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 o invoke [sqlite
36db0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 3_blob_close()]
36dc0 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 on *ppBlob.** re
36dd0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
36de0 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 success or failu
36df0 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 re of this routi
36e00 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 ne..**.** ^(If t
36e10 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c he row that a BL
36e20 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 OB handle points
36e30 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 to is modified
36e40 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 by an.** [UPDATE
36e50 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 ], [DELETE], or
36e60 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d by [ON CONFLICT]
36e70 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a side-effects.**
36e80 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 then the BLOB h
36e90 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 andle is marked
36ea0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a as "expired"..**
36eb0 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 This is true if
36ec0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 any column of t
36ed0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 he row is change
36ee0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e d, even a column
36ef0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 .** other than t
36f00 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 he one the BLOB
36f10 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f handle is open o
36f20 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 n.)^.** ^Calls t
36f30 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
36f40 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c read()] and [sql
36f50 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
36f60 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 )] for.** a expi
36f70 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 red BLOB handle
36f80 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 fail with an ret
36f90 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c urn code of [SQL
36fa0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e ITE_ABORT]..** ^
36fb0 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e (Changes written
36fc0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 into a BLOB pri
36fd0 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 or to the BLOB e
36fe0 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a xpiring are not.
36ff0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ** rolled back b
37000 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e y the expiration
37010 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 of the BLOB. S
37020 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c uch changes will
37030 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 eventually.** c
37040 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 ommit if the tra
37050 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 nsaction continu
37060 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
37070 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 .)^.**.** ^Use t
37080 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
37090 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
370a0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ace to determine
370b0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
370c0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e the opened blob.
370d0 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 ^The size of a
370e0 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 blob may not be
370f0 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 changed by this
37100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 .** interface.
37110 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d Use the [UPDATE]
37120 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 SQL command to
37130 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 change the size
37140 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a of a.** blob..**
37150 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
37160 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
37170 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
37180 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
37190 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
371a0 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 and the built-i
371b0 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c n [zeroblob] SQL
371c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 function can be
371d0 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 used, if desire
371e0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 d,.** to create
371f0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 an empty, zero-f
37200 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 illed blob in wh
37210 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 ich to read or w
37220 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 rite using.** th
37230 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
37240 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 .** To avoid a r
37250 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 esource leak, ev
37260 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 ery open [BLOB h
37270 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 andle] should ev
37280 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 entually.** be r
37290 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c eleased by a cal
372a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
372b0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a ob_close()]..*/.
372c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
372d0 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 _open(. sqlite3
372e0 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 *,. const char
372f0 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *zDb,. const ch
37300 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f ar *zTable,. co
37310 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d nst char *zColum
37320 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 n,. sqlite3_int
37330 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 64 iRow,. int f
37340 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f lags,. sqlite3_
37350 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b blob **ppBlob.);
37360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37370 3a 20 4d 6f 76 65 20 61 20 42 4c 4f 42 20 48 61 : Move a BLOB Ha
37380 6e 64 6c 65 20 74 6f 20 61 20 4e 65 77 20 52 6f ndle to a New Ro
37390 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 w.**.** ^This fu
373a0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 nction is used t
373b0 6f 20 6d 6f 76 65 20 61 6e 20 65 78 69 73 74 69 o move an existi
373c0 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 73 ng blob handle s
373d0 6f 20 74 68 61 74 20 69 74 20 70 6f 69 6e 74 73 o that it points
373e0 0a 2a 2a 20 74 6f 20 61 20 64 69 66 66 65 72 65 .** to a differe
373f0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 73 61 nt row of the sa
37400 6d 65 20 64 61 74 61 62 61 73 65 20 74 61 62 6c me database tabl
37410 65 2e 20 5e 54 68 65 20 6e 65 77 20 72 6f 77 20 e. ^The new row
37420 69 73 20 69 64 65 6e 74 69 66 69 65 64 0a 2a 2a is identified.**
37430 20 62 79 20 74 68 65 20 72 6f 77 69 64 20 76 61 by the rowid va
37440 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
37450 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
37460 74 2e 20 4f 6e 6c 79 20 74 68 65 20 72 6f 77 20 t. Only the row
37470 63 61 6e 20 62 65 0a 2a 2a 20 63 68 61 6e 67 65 can be.** change
37480 64 2e 20 5e 54 68 65 20 64 61 74 61 62 61 73 65 d. ^The database
37490 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 , table and colu
374a0 6d 6e 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 mn on which the
374b0 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20 6f blob handle is o
374c0 70 65 6e 0a 2a 2a 20 72 65 6d 61 69 6e 20 74 68 pen.** remain th
374d0 65 20 73 61 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 e same. Moving a
374e0 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 n existing blob
374f0 68 61 6e 64 6c 65 20 74 6f 20 61 20 6e 65 77 20 handle to a new
37500 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20 66 61 row can be.** fa
37510 73 74 65 72 20 74 68 61 6e 20 63 6c 6f 73 69 6e ster than closin
37520 67 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 68 g the existing h
37530 61 6e 64 6c 65 20 61 6e 64 20 6f 70 65 6e 69 6e andle and openin
37540 67 20 61 20 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a g a new one..**.
37550 2a 2a 20 5e 28 54 68 65 20 6e 65 77 20 72 6f 77 ** ^(The new row
37560 20 6d 75 73 74 20 6d 65 65 74 20 74 68 65 20 73 must meet the s
37570 61 6d 65 20 63 72 69 74 65 72 69 61 20 61 73 20 ame criteria as
37580 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f for [sqlite3_blo
37590 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69 b_open()] -.** i
375a0 74 20 6d 75 73 74 20 65 78 69 73 74 20 61 6e 64 t must exist and
375b0 20 74 68 65 72 65 20 6d 75 73 74 20 62 65 20 65 there must be e
375c0 69 74 68 65 72 20 61 20 62 6c 6f 62 20 6f 72 20 ither a blob or
375d0 74 65 78 74 20 76 61 6c 75 65 20 73 74 6f 72 65 text value store
375e0 64 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 6f 6d 69 d in.** the nomi
375f0 6e 61 74 65 64 20 63 6f 6c 75 6d 6e 2e 29 5e 20 nated column.)^
37600 5e 49 66 20 74 68 65 20 6e 65 77 20 72 6f 77 20 ^If the new row
37610 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 is not present i
37620 6e 20 74 68 65 20 74 61 62 6c 65 2c 20 6f 72 20 n the table, or
37630 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f if.** it does no
37640 74 20 63 6f 6e 74 61 69 6e 20 61 20 62 6c 6f 62 t contain a blob
37650 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65 2c 20 or text value,
37660 6f 72 20 69 66 20 61 6e 6f 74 68 65 72 20 65 72 or if another er
37670 72 6f 72 20 6f 63 63 75 72 73 2c 20 61 6e 0a 2a ror occurs, an.*
37680 2a 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 * SQLite error c
37690 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
376a0 61 6e 64 20 74 68 65 20 62 6c 6f 62 20 68 61 6e and the blob han
376b0 64 6c 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65 dle is considere
376c0 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a 20 5e 41 d aborted..** ^A
376d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ll subsequent ca
376e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
376f0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c 20 5b 73 blob_read()], [s
37700 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
37710 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 e()] or.** [sqli
37720 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 te3_blob_reopen(
37730 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64 )] on an aborted
37740 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 6d 6d blob handle imm
37750 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 0a ediately return.
37760 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e ** SQLITE_ABORT.
37770 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 ^Calling [sqlit
37780 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d e3_blob_bytes()]
37790 20 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64 20 62 on an aborted b
377a0 6c 6f 62 20 68 61 6e 64 6c 65 0a 2a 2a 20 61 6c lob handle.** al
377b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 ways returns zer
377c0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 o..**.** ^This f
377d0 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 unction sets the
377e0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
377f0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
37800 6d 65 73 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49 message..*/.SQLI
37810 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
37820 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
37830 5f 72 65 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f _reopen(sqlite3_
37840 62 6c 6f 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f blob *, sqlite3_
37850 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
37860 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 API3REF: Close A
37870 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a BLOB Handle.**.
37880 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 ** ^Closes an op
37890 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
378a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 ..**.** ^Closing
378b0 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 a BLOB shall ca
378c0 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 use the current
378d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 transaction to c
378e0 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 ommit.** if ther
378f0 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 e are no other B
37900 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 LOBs, no pending
37910 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
37920 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a ents, and the.**
37930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
37940 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f tion is in [auto
37950 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a commit mode]..**
37960 20 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 ^If any writes
37970 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 were made to the
37980 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 BLOB, they migh
37990 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 t be held in cac
379a0 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 he.** until the
379b0 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 close operation
379c0 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 if they will fit
379d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e ..**.** ^(Closin
379e0 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e g the BLOB often
379f0 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e forces the chan
37a00 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 ges.** out to di
37a10 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 sk and so if any
37a20 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 I/O errors occu
37a30 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b r, they will lik
37a40 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 ely occur.** at
37a50 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 the time when th
37a60 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 e BLOB is closed
37a70 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 . Any errors th
37a80 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a at occur during.
37a90 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 ** closing are r
37aa0 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e eported as a non
37ab0 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c -zero return val
37ac0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ue.)^.**.** ^(Th
37ad0 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 e BLOB is closed
37ae0 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 unconditionally
37af0 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 . Even if this
37b00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a routine returns.
37b10 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 ** an error code
37b20 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 , the BLOB is st
37b30 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a ill closed.)^.**
37b40 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
37b50 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
37b60 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 null pointer (s
37b70 75 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 uch as would be
37b80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 returned.** by a
37b90 20 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 failed call to
37ba0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
37bb0 65 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d en()]) is a harm
37bc0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 less no-op..*/.i
37bd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
37be0 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c close(sqlite3_bl
37bf0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
37c00 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 PI3REF: Return T
37c10 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 he Size Of An Op
37c20 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 en BLOB.**.** ^R
37c30 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 eturns the size
37c40 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 in bytes of the
37c50 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 BLOB accessible
37c60 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 via the .** succ
37c70 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 essfully opened
37c80 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e [BLOB handle] in
37c90 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 its only argume
37ca0 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 nt. ^The.** inc
37cb0 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f remental blob I/
37cc0 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f O routines can o
37cd0 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 nly read or over
37ce0 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 writing existing
37cf0 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 .** blob content
37d00 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 ; they cannot ch
37d10 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 ange the size of
37d20 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 a blob..**.** T
37d30 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
37d40 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f works on a [BLO
37d50 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 B handle] which
37d60 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 has been created
37d70 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 .** by a prior s
37d80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
37d90 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
37da0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 open()] and whic
37db0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 h has not.** bee
37dc0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c n closed by [sql
37dd0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
37de0 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 )]. Passing any
37df0 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 other pointer i
37e00 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 n.** to this rou
37e10 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 tine results in
37e20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
37e30 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
37e40 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a le behavior..*/.
37e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
37e60 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 _bytes(sqlite3_b
37e70 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
37e80 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 API3REF: Read Da
37e90 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 ta From A BLOB I
37ea0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a ncrementally.**.
37eb0 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 ** ^(This functi
37ec0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 on is used to re
37ed0 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 ad data from an
37ee0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
37ef0 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c e] into a.** cal
37f00 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 ler-supplied buf
37f10 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 fer. N bytes of
37f20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 data are copied
37f30 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a into buffer Z.**
37f40 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 from the open B
37f50 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
37f60 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
37f70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 )^.**.** ^If off
37f80 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c set iOffset is l
37f90 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 ess than N bytes
37fa0 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 from the end of
37fb0 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 the BLOB,.** [S
37fc0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
37fd0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
37fe0 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e data is read. ^
37ff0 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 If N or iOffset
38000 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 is.** less than
38010 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 zero, [SQLITE_ER
38020 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
38030 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
38040 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 read..** ^The si
38050 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 ze of the blob (
38060 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 and hence the ma
38070 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e ximum value of N
38080 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e +iOffset).** can
38090 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
380a0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
380b0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
380c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
380d0 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 ^An attempt to
380e0 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 read from an exp
380f0 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ired [BLOB handl
38100 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e e] fails with an
38110 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f .** error code o
38120 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d f [SQLITE_ABORT]
38130 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 ..**.** ^(On suc
38140 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c cess, sqlite3_bl
38150 6f 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e ob_read() return
38160 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 s SQLITE_OK..**
38170 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 Otherwise, an [e
38180 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
38190 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
381a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
381b0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ed.)^.**.** This
381c0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f routine only wo
381d0 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 rks on a [BLOB h
381e0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 andle] which has
381f0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a been created.**
38200 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 by a prior succ
38210 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
38220 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
38230 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 n()] and which h
38240 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 as not.** been c
38250 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 losed by [sqlite
38260 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
38270 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 Passing any ot
38280 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a her pointer in.*
38290 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e * to this routin
382a0 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 e results in und
382b0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
382c0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 bly undesirable
382d0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
382e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
382f0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
38300 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
38310 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 _blob_read(sqlit
38320 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 e3_blob *, void
38330 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 *Z, int N, int i
38340 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
38350 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 CAPI3REF: Write
38360 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 Data Into A BLOB
38370 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a Incrementally.*
38380 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
38390 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 ion is used to w
383a0 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 rite data into a
383b0 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e n open [BLOB han
383c0 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 dle] from a.** c
383d0 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 aller-supplied b
383e0 75 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 uffer. ^N bytes
383f0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
38400 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 ed from the buff
38410 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 er Z.** into the
38420 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 open BLOB, star
38430 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 ting at offset i
38440 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 Offset..**.** ^I
38450 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 f the [BLOB hand
38460 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 le] passed as th
38470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
38480 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 was not opened
38490 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 for.** writing (
384a0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 the flags parame
384b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
384c0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 blob_open()] was
384d0 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 zero),.** this
384e0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
384f0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c [SQLITE_READONL
38500 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 Y]..**.** ^This
38510 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c function may onl
38520 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e y modify the con
38530 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f tents of the BLO
38540 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 B; it is.** not
38550 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 possible to incr
38560 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 ease the size of
38570 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 a BLOB using th
38580 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f is API..** ^If o
38590 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
385a0 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
385b0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
385c0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
385d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
385e0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
385f0 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 o data is writte
38600 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 n. ^If N is.**
38610 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b less than zero [
38620 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
38630 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
38640 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e data is written
38650 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 ..** The size of
38660 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 the BLOB (and h
38670 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d ence the maximum
38680 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 value of N+iOff
38690 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 set).** can be d
386a0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 etermined using
386b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
386c0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
386d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 face..**.** ^An
386e0 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 attempt to write
386f0 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b to an expired [
38700 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
38710 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
38720 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
38730 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 ITE_ABORT]. ^Wr
38740 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 ites to the BLOB
38750 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a that occurred.*
38760 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c * before the [BL
38770 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 OB handle] expir
38780 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 ed are not rolle
38790 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a d back by the.**
387a0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 expiration of t
387b0 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 he handle, thoug
387c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 h of course thos
387d0 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a e changes might.
387e0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 ** have been ove
387f0 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 rwritten by the
38800 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 statement that e
38810 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 xpired the BLOB
38820 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 handle.** or by
38830 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e other independen
38840 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a t statements..**
38850 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 .** ^(On success
38860 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 , sqlite3_blob_w
38870 72 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 rite() returns S
38880 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 QLITE_OK..** Oth
38890 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 erwise, an [err
388a0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b or code] or an [
388b0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
388c0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
388d0 2e 29 5e 0a 2a 2a 0a 2a