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 2a 0a 2a me systems..**.*
7fb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
7fc0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
7fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
7fe0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
7ff0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
8000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
8010: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
8020: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
8030: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
8040: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 nnection. See t
8050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8060: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 _control()] docu
8070: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
8080: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
8090: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 rmation..*/.#def
80a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
80b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 _LOCKSTATE
80c0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
80d0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_GET_LOCKPROXY
80e0: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 FILE 2.#def
80f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
8100: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
8110: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
8120: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 TE_LAST_ERRNO
8130: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
8140: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
8150: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
8160: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
8170: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
8180: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 IZE 6.#def
8190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
81a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 _FILE_POINTER
81b0: 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 7.../*.** CAPI
81c0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 3REF: Mutex Hand
81d0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 le.**.** The mut
81e0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e ex module within
81f0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 SQLite defines
8200: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
8210: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 to be an.** abst
8220: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 ract type for a
8230: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 mutex object. T
8240: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e he SQLite core n
8250: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 ever looks.** at
8260: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
8270: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 presentation of
8280: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 an [sqlite3_mute
8290: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 x]. It only.**
82a0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 deals with point
82b0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ers to the [sqli
82c0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 te3_mutex] objec
82d0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 t..**.** Mutexes
82e0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 are created usi
82f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
8300: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 x_alloc()]..*/.t
8310: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
8320: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 lite3_mutex sqli
8330: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a te3_mutex;../*.*
8340: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
8350: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a nterface Object.
8360: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
8370: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
8380: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 _vfs object defi
8390: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
83a0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 e between.** the
83b0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 SQLite core and
83c0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
83d0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
83e0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 . The "vfs".**
83f0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 in the name of t
8400: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 he object stands
8410: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 for "virtual fi
8420: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a le system"..**.*
8430: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * The value of t
8440: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
8450: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 d is initially 1
8460: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
8470: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 er in.** future
8480: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
8490: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 te. Additional
84a0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
84b0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a pended to this.*
84c0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 * object when th
84d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 e iVersion value
84e0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 is increased.
84f0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 Note that the st
8500: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 ructure.** of th
8510: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
8520: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 ject changes in
8530: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
8540: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 between.** SQLit
8550: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 e version 3.5.9
8560: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 and 3.6.0 and ye
8570: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 t the iVersion f
8580: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 ield was not.**
8590: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 modified..**.**
85a0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 The szOsFile fie
85b0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f ld is the size o
85c0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 f the subclassed
85d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a [sqlite3_file].
85e0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 ** structure use
85f0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 d by this VFS.
8600: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 mxPathname is th
8610: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
8620: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d of.** a pathnam
8630: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a e in this VFS..*
8640: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 *.** Registered
8650: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
8660: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 cts are kept on
8670: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f a linked list fo
8680: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 rmed by.** the p
8690: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 Next pointer. T
86a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
86b0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 register()].** a
86c0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f nd [sqlite3_vfs_
86d0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e unregister()] in
86e0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 terfaces manage
86f0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 this list.** in
8700: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 a thread-safe wa
8710: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 y. The [sqlite3
8720: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 _vfs_find()] int
8730: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 erface.** search
8740: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 es the list. Ne
8750: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 ither the applic
8760: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 ation code nor t
8770: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d he VFS.** implem
8780: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
8790: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f use the pNext po
87a0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
87b0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 pNext field is
87c0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 the only field i
87d0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
87e0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 s.** structure t
87f0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
8800: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 ever modify. SQ
8810: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 Lite will only a
8820: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 ccess.** or modi
8830: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 fy this field wh
8840: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 ile holding a pa
8850: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 rticular static
8860: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 mutex..** The ap
8870: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
8880: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e never modify an
8890: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 ything within th
88a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
88b0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 object once the
88c0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e object has been
88d0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a registered..**.
88e0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 ** The zName fie
88f0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d ld holds the nam
8900: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 e of the VFS mod
8910: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d ule. The name m
8920: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 ust.** be unique
8930: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 across all VFS
8940: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e modules..**.** ^
8950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
8960: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 s that the zFile
8970: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
8980: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 o xOpen.** is ei
8990: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
89a0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 ter or string ob
89b0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 tained.** from x
89c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 FullPathname() w
89d0: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 ith an optional
89e0: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a suffix added..**
89f0: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 ^If a suffix is
8a00: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 added to the zF
8a10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
8a20: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f r, it will.** co
8a30: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c nsist of a singl
8a40: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 e "-" character
8a50: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d followed by no m
8a60: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 ore than.** 10 a
8a70: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f lphanumeric and/
8a80: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 or "-" character
8a90: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 s..** ^SQLite fu
8aa0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 rther guarantees
8ab0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 that.** the str
8ac0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ing will be vali
8ad0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 d and unchanged
8ae0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 until xClose() i
8af0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 s.** called. Bec
8b00: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 ause of the prev
8b10: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a ious sentence,.*
8b20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 * the [sqlite3_f
8b30: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 ile] can safely
8b40: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 store a pointer
8b50: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 to the.** filena
8b60: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 me if it needs t
8b70: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 o remember the f
8b80: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 ilename for some
8b90: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 reason..** If t
8ba0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
8bb0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 ameter to xOpen
8bc0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
8bd0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 r then xOpen.**
8be0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 must invent its
8bf0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 own temporary na
8c00: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e me for the file.
8c10: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 ^Whenever the
8c20: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 .** xFilename pa
8c30: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 rameter is NULL
8c40: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 it will also be
8c50: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
8c60: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d e.** flags param
8c70: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 eter will includ
8c80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
8c90: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a ELETEONCLOSE]..*
8ca0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
8cb0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
8cc0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
8cd0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 bits set in.** t
8ce0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
8cf0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
8d00: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 en_v2()]. Or if
8d10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
8d20: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
8d30: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 _open16()] is us
8d40: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 ed, then flags i
8d50: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 ncludes at least
8d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
8d70: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
8d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
8d90: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e E]. .** If xOpen
8da0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 () opens a file
8db0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 read-only then i
8dc0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 t sets *pOutFlag
8dd0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 s to.** include
8de0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
8df0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 DONLY]. Other b
8e00: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 its in *pOutFlag
8e10: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a s may be set..**
8e20: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c .** ^(SQLite wil
8e30: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f l also add one o
8e40: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
8e50: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
8e60: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 en().** call, de
8e70: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
8e80: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e bject being open
8e90: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ed:.**.** <ul>.*
8ea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
8eb0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a OPEN_MAIN_DB].**
8ec0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
8ed0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
8ee0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
8ef0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d TE_OPEN_TEMP_DB]
8f00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
8f20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
8f30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
8f40: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e IENT_DB].** <li>
8f50: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 [SQLITE_OPEN_S
8f60: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c UBJOURNAL].** <l
8f70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
8f80: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d _MASTER_JOURNAL]
8f90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8fa0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c E_OPEN_WAL].** <
8fb0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 /ul>)^.**.** The
8fc0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d file I/O implem
8fd0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 entation can use
8fe0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 the object type
8ff0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 flags to.** cha
9000: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 nge the way it d
9010: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e eals with files.
9020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 For example, a
9030: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a n application.**
9040: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 that does not c
9050: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 are about crash
9060: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c recovery or roll
9070: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a back might make.
9080: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 ** the open of a
9090: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 journal file a
90a0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 no-op. Writes t
90b0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 o this journal w
90c0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 ould.** also be
90d0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 no-ops, and any
90e0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
90f0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c the journal woul
9100: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 d return.** SQLI
9110: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 TE_IOERR. Or th
9120: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
9130: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 might recognize
9140: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 that a database
9150: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 .** file will be
9160: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
9170: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
9180: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
9190: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 random.** order
91a0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
91b0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
91c0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a cordingly..**.**
91d0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c SQLite might al
91e0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
91f0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
9200: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d s to the xOpen m
9210: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
9220: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
9230: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
9240: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 LOSE].** <li> [S
9250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
9260: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a SIVE].** </ul>.*
9270: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
9280: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
9290: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 OSE] flag means
92a0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
92b0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 be.** deleted wh
92c0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e en it is closed.
92d0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ^The [SQLITE_O
92e0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
92f0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 E].** will be se
9300: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 t for TEMP datab
9310: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a ases and their j
9320: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 ournals, transie
9330: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c nt.** databases,
9340: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 and subjournals
9350: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ..**.** ^The [SQ
9360: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
9370: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 IVE] flag is alw
9380: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a ays used in conj
9390: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
93a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
93b0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 _CREATE] flag, w
93c0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 hich are both di
93d0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 rectly.** analog
93e0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 ous to the O_EXC
93f0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c L and O_CREAT fl
9400: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 ags of the POSIX
9410: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 open().** API.
9420: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e The SQLITE_OPEN
9430: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c _EXCLUSIVE flag,
9440: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 when paired wit
9450: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 h the .** SQLITE
9460: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 _OPEN_CREATE, is
9470: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 used to indicat
9480: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 e that file shou
9490: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ld always.** be
94a0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 created, and tha
94b0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 t it is an error
94c0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 if it already e
94d0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 xists..** It is
94e0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 <i>not</i> used
94f0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 to indicate the
9500: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f file should be o
9510: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 pened .** for ex
9520: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a clusive access..
9530: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 **.** ^At least
9540: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f szOsFile bytes o
9550: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c f memory are all
9560: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
9570: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 .** to hold the
9580: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
9590: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 structure passed
95a0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a as the third.**
95b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
95c0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d en. The xOpen m
95d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 ethod does not h
95e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 ave to.** alloca
95f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 te the structure
9600: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 ; it should just
9610: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f fill it in. No
9620: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 te that.** the x
9630: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 Open method must
9640: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
9650: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 _file.pMethods t
9660: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 o either.** a va
9670: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f lid [sqlite3_io_
9680: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
9690: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 or to NULL. xOp
96a0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 en must do.** th
96b0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f is even if the o
96c0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 pen fails. SQLi
96d0: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 te expects that
96e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
96f0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 .pMethods.** ele
9700: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c ment will be val
9710: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 id after xOpen r
9720: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 eturns regardles
9730: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 s of the success
9740: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f .** or failure o
9750: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c f the xOpen call
9760: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 ..**.** ^The fla
9770: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
9780: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 Access() may be
9790: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 [SQLITE_ACCESS_E
97a0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 XISTS].** to tes
97b0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 t for the existe
97c0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f nce of a file, o
97d0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
97e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a _READWRITE] to.*
97f0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 * test whether a
9800: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
9810: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
9820: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
9830: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 S_READ].** to te
9840: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
9850: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 e is at least re
9860: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 adable. The fi
9870: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
9880: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
9890: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 ^SQLite will alw
98a0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
98b0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
98c0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
98d0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
98e0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
98f0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 The exact size
9900: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
9910: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
9920: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
9930: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
9940: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 methods. If the
9950: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
9960: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
9970: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
9980: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
9990: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
99a0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
99b0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
99c0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
99d0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
99e0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
99f0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
9a00: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
9a10: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
9a20: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
9a30: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
9a40: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
9a50: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
9a60: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 xCurrentTime(),
9a70: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
9a80: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 Int64().** inter
9a90: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 faces are not st
9aa0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
9ab0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
9ac0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
9ad0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
9ae0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
9af0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
9b00: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
9b10: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
9b20: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
9b30: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
9b40: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
9b50: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
9b60: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
9b70: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
9b80: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
9b90: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
9ba0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
9bb0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
9bc0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
9bd0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
9be0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
9bf0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
9c00: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
9c10: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
9c20: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
9c30: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
9c40: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
9c50: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
9c60: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
9c70: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 nd time as.** a
9c80: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
9c90: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 alue..** ^The xC
9ca0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
9cb0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
9cc0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c , as an integer,
9cd0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 the Julian.** D
9ce0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 ay Number multip
9cf0: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 led by 86400000
9d00: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
9d10: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
9d20: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
9d30: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
9d40: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
9d50: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
9d60: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
9d70: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
9d80: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
9d90: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
9da0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
9db0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
9dc0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
9dd0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
9de0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
9df0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
9e00: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
9e10: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
9e20: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
9e30: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f unavailable..*/
9e40: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
9e50: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 sqlite3_vfs sqli
9e60: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 te3_vfs;.struct
9e70: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
9e80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
9e90: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
9ea0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
9eb0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
9ec0: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 2) */. int szOs
9ed0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
9ee0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
9ef0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
9f00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
9f10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
9f20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
9f30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
9f40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
9f50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
9f60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
9f70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
9f80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
9f90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
9fa0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
9fb0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
9fc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
9fd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
9fe0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
9ff0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
a000: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
a010: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
a020: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
a030: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
a040: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
a050: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
a060: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
a070: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
a080: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
a090: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
a0a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
a0b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
a0c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
a0d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
a0e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
a0f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
a100: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
a110: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
a120: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
a130: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
a140: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
a150: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
a160: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
a170: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
a180: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
a190: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
a1a0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
a1b0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
a1c0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
a1d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
a1e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
a1f0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
a200: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
a210: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
a220: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
a230: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
a240: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
a250: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
a260: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
a270: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
a280: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
a290: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
a2a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
a2b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
a2c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
a2d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
a2e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
a2f0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
a300: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
a310: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
a320: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
a330: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
a340: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
a350: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
a360: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
a370: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
a380: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
a390: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
a3a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
a3b0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
a3c0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
a3d0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
a3e0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
a3f0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
a400: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
a410: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
a420: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
a430: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e figure versions.
a440: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
a450: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
a460: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
a470: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
a480: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 . */.};../*.**
a490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
a4a0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
a4b0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
a4c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
a4d0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
a4e0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
a4f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
a500: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
a510: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
a520: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
a530: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
a540: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
a550: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
a560: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
a570: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
a580: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
a590: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
a5a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
a5b0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
a5c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
a5d0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
a5e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
a5f0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
a600: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
a610: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
a620: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 the named direc
a630: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 tory is both rea
a640: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
a650: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 le.** (in other
a660: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 words, if files
a670: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 can be added, re
a680: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d moved, and renam
a690: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
a6a0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 directory)..**
a6b0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
a6c0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 S_READWRITE cons
a6d0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c tant is currentl
a6e0: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 y used only by t
a6f0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 he.** [temp_stor
a700: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 e_directory prag
a710: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 ma], though this
a720: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e could change in
a730: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c a future.** rel
a740: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
a750: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
a760: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 CCESS_READ, the
a770: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
a780: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
a790: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 the file is rea
a7a0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 dable. The SQLI
a7b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 TE_ACCESS_READ c
a7c0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 onstant is.** cu
a7d0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 rrently unused,
a7e0: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 though it might
a7f0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 be used in a fut
a800: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
a810: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 * SQLite..*/.#de
a820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
a830: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
a840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
a850: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
a860: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 /* Used by PR
a870: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f AGMA temp_store_
a880: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 directory */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
a8a0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 SS_READ 2
a8b0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f /* Unused */../
a8c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
a8d0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 lags for the xSh
a8e0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 mLock VFS method
a8f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
a900: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 eger constants d
a910: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 efine the variou
a920: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 s locking operat
a930: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 ions.** allowed
a940: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 by the xShmLock
a950: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 method of [sqlit
a960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 e3_io_methods].
a970: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e The.** followin
a980: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c g are the only l
a990: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e egal combination
a9a0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 s of flags to th
a9b0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 e.** xShmLock me
a9c0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
a9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
a9e0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
a9f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
aa00: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
aa10: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
aa20: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
aa30: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
aa40: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
aa50: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
aa60: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
aa70: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
aa80: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
aa90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 * </ul>.**.** Wh
aaa0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 en unlocking, th
aab0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 e same SHARED or
aac0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 EXCLUSIVE flag
aad0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 must be supplied
aae0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e as.** was given
aaf0: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f no the correspo
ab00: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a nding lock. .**
ab10: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
ab20: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e method can tran
ab30: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 sition between u
ab40: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 nlocked and SHAR
ab50: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e ED or.** between
ab60: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 unlocked and EX
ab70: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e CLUSIVE. It can
ab80: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 not transition b
ab90: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a etween SHARED.**
aba0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a and EXCLUSIVE..
abb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
abc0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 E_SHM_UNLOCK
abd0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
abe0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 ITE_SHM_LOCK
abf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
ac00: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
ac10: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
ac20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
ac30: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a USIVE 8../*.*
ac40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 * CAPI3REF: Maxi
ac50: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 mum xShmLock ind
ac60: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 ex.**.** The xSh
ac70: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 mLock method on
ac80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
ac90: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c ods] may use val
aca0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 ues.** between 0
acb0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 and this upper
acc0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 bound as its "of
acd0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a fset" argument..
ace0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
acf0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 re will never at
ad00: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 tempt to acquire
ad10: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a or release a.**
ad20: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 lock outside of
ad30: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 this range.*/.#
ad40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
ad50: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 M_NLOCK 8
ad60: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
ad70: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
ad80: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
ad90: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
ada0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
adb0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
adc0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
add0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 te library. ^Th
ade0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
adf0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
ae00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
ae10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
ae20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
ae30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
ae40: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 ize()..** These
ae50: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
ae60: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 igned to aid in
ae70: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
ae80: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 zation and.** sh
ae90: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 utdown on embedd
aea0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 ed systems. Wor
aeb0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 kstation applica
aec0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 tions using.** S
aed0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 QLite normally d
aee0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e o not need to in
aef0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 voke either of t
af00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
af10: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
af20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
af30: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
af40: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
af50: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
af60: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
af70: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
af80: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
af90: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
afa0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
afb0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
afc0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
afd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
afe0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
aff0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
b000: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
b010: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 ). ^(Only an ef
b020: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 fective call.**
b030: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 of sqlite3_initi
b040: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 alize() does any
b050: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e initialization.
b060: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c All other call
b070: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 s.** are harmles
b080: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
b090: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
b0a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
b0b0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
b0c0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
b0d0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
b0e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
b0f0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
b100: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
b110: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f itialize(). ^(O
b120: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 nly.** an effect
b130: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ive call to sqli
b140: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 te3_shutdown() d
b150: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 oes any deinitia
b160: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c lization..** All
b170: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c other valid cal
b180: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
b190: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
b1a0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
b1b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
b1c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
b1d0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 nterface is thre
b1e0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 adsafe, but sqli
b1f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
b200: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 * is not. The s
b210: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
b220: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 ) interface must
b230: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
b240: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 from a.** single
b250: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 thread. All op
b260: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
b270: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 nections] must b
b280: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c e closed and all
b290: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 .** other SQLite
b2a0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 resources must
b2b0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 be deallocated p
b2c0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 rior to invoking
b2d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 .** sqlite3_shut
b2e0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d down()..**.** Am
b2f0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 ong other things
b300: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 , ^sqlite3_initi
b310: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 alize() will inv
b320: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f oke.** sqlite3_o
b330: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c s_init(). Simil
b340: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 arly, ^sqlite3_s
b350: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c hutdown().** wil
b360: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 l invoke sqlite3
b370: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a _os_end()..**.**
b380: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
b390: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
b3a0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
b3b0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
b3c0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f s..** ^If for so
b3d0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
b3e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
b3f0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
b400: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
b410: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
b420: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
b430: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
b440: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
b450: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
b460: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
b470: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
b480: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
b490: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
b4a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
b4b0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
b4c0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
b4d0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
b4e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
b4f0: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
b500: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
b510: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
b520: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
b530: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
b540: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
b550: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
b560: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
b570: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
b580: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
b590: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
b5a0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
b5b0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
b5c0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
b5d0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
b5e0: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
b5f0: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
b600: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f ** already. ^Ho
b610: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
b620: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
b630: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d h the [SQLITE_OM
b640: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 IT_AUTOINIT].**
b650: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
b660: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 ion, then the au
b670: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f tomatic calls to
b680: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
b690: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 ize().** are omi
b6a0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 tted and the app
b6b0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 lication must ca
b6c0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ll sqlite3_initi
b6d0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
b6e0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 .** prior to usi
b6f0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
b700: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
b710: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 For maximum port
b720: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 ability,.** it i
b730: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
b740: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 at applications
b750: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 always invoke sq
b760: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
b770: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 ().** directly p
b780: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
b790: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
b7a0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 nterface. Futur
b7b0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 e releases.** of
b7c0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 SQLite may requ
b7d0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 ire this. In ot
b7e0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 her words, the b
b7f0: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 ehavior exhibite
b800: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 d.** when SQLite
b810: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
b820: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 h [SQLITE_OMIT_A
b830: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 UTOINIT] might b
b840: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 ecome the.** def
b850: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e ault behavior in
b860: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
b870: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
b880: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
b890: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 3_os_init() rout
b8a0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 ine does operati
b8b0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
b8c0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 ic.** initializa
b8d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
b8e0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
b8f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
b900: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 ).** routine und
b910: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
b920: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
b930: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 t(). Typical ta
b940: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 sks.** performed
b950: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e by these routin
b960: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 es include alloc
b970: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 ation or dealloc
b980: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 ation.** of stat
b990: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e ic resources, in
b9a0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
b9b0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 global variables
b9c0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 ,.** setting up
b9d0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 a default [sqlit
b9e0: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 e3_vfs] module,
b9f0: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a or setting up.**
ba00: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 a default confi
ba10: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b guration using [
ba20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ba30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 ]..**.** The app
ba40: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
ba50: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 never invoke eit
ba60: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 her sqlite3_os_i
ba70: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 nit().** or sqli
ba80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 te3_os_end() dir
ba90: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c ectly. The appl
baa0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f ication should o
bab0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 nly invoke.** sq
bac0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
bad0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 () and sqlite3_s
bae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 hutdown(). The
baf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
bb00: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
bb10: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 s called automat
bb20: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
bb30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
bb40: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 nd.** sqlite3_os
bb50: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 _end() is called
bb60: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 by sqlite3_shut
bb70: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 down(). Appropr
bb80: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e iate.** implemen
bb90: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 tations for sqli
bba0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
bbb0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
bbc0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 ().** are built
bbd0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e into SQLite when
bbe0: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 it is compiled
bbf0: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 for Unix, Window
bc00: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 s, or OS/2..** W
bc10: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c hen [custom buil
bc20: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f ds | built for o
bc30: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a ther platforms].
bc40: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 ** (using the [S
bc50: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 QLITE_OS_OTHER=1
bc60: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
bc70: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 * option) the ap
bc80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
bc90: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 upply a suitable
bca0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
bcb0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
bcc0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
bcd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 ite3_os_end().
bce0: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 An application-s
bcf0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 upplied.** imple
bd00: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
bd10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f ite3_os_init() o
bd20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
bd30: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 ().** must retur
bd40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
bd50: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d success and som
bd60: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 e other [error c
bd70: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 ode] upon.** fai
bd80: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lure..*/.int sql
bd90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
bda0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
bdb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
bdc0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
bdd0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e s_init(void);.in
bde0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 t sqlite3_os_end
bdf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
be00: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
be10: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 ring The SQLite
be20: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 Library.**.** Th
be30: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
be40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
be50: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
be60: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
be70: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
be80: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
be90: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
bea0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
beb0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
bec0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
bed0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
bee0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
bef0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
bf00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
bf10: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
bf20: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
bf30: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
bf40: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
bf50: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
bf60: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
bf70: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
bf80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
bf90: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
bfa0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
bfb0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
bfc0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
bfd0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
bfe0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
bff0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
c000: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
c010: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
c020: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
c030: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
c040: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
c050: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
c060: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
c070: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
c080: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
c090: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
c0a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
c0b0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
c0c0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
c0d0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
c0e0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ^If sqlite3_conf
c0f0: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 ig() is called a
c100: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e fter [sqlite3_in
c110: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 itialize()] and
c120: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 before.** [sqlit
c130: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 e3_shutdown()] t
c140: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 hen it will retu
c150: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 rn SQLITE_MISUSE
c160: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 ..** Note, howev
c170: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 er, that ^sqlite
c180: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 3_config() can b
c190: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 e called as part
c1a0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 of the.** imple
c1b0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 mentation of an
c1c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
c1d0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f ned [sqlite3_os_
c1e0: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 init()]..**.** T
c1f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
c200: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e t to sqlite3_con
c210: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 fig() is an inte
c220: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 ger.** [SQLITE_C
c230: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
c240: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
c250: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
c260: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
c270: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
c280: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
c290: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
c2a0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
c2b0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
c2c0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 ng on the [SQLIT
c2d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
c2e0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 HREAD | configur
c2f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
c300: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
c310: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
c320: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
c330: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
c340: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
c350: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
c360: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
c370: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
c380: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
c390: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
c3a0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
c3b0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
c3c0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
c3d0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
c3e0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
c3f0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
c400: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
c410: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
c420: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c430: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
c440: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
c450: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
c460: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
c470: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
c480: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
c490: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
c4a0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
c4b0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
c4c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
c4d0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
c4e0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
c4f0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
c500: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
c510: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
c520: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
c530: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a gument). The.**
c540: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
c550: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ig() interface s
c560: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 hould only be us
c570: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 ed immediately a
c580: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 fter.** the data
c590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
c5a0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 is created using
c5b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
c5c0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f ],.** [sqlite3_o
c5d0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 pen16()], or [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
c5f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 . .**.** The se
c600: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
c610: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
c620: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
c630: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 the.** configura
c640: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 tion verb - an i
c650: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
c660: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a indicates what.
c670: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 ** aspect of the
c680: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
c690: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
c6a0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 configured..** T
c6b0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 he only choice f
c6c0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 or this value is
c6d0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
c6e0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a G_LOOKASIDE]..**
c6f0: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c New verbs are l
c700: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 ikely to be adde
c710: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
c720: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
c730: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 ** Additional ar
c740: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f guments depend o
c750: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a n the verb..**.*
c760: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
c770: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
c780: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
c790: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
c7a0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
c7b0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
c7c0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c sful..*/.int sql
c7d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 ite3_db_config(s
c7e0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c qlite3*, int op,
c7f0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
c800: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
c810: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e llocation Routin
c820: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 es.**.** An inst
c830: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
c840: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
c850: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
c860: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
c870: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
c880: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
c890: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
c8a0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
c8b0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
c8c0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
c8d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
c8e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
c8f0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
c900: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
c910: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
c920: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
c930: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
c940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
c950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
c960: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
c970: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
c980: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
c990: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
c9a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
c9b0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
c9c0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
c9d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
c9e0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
c9f0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
ca00: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
ca10: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
ca20: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
ca30: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
ca40: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
ca50: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
ca60: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
ca70: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
ca80: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
ca90: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
caa0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
cab0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
cac0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
cad0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
cae0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
caf0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
cb00: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
cb10: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
cb20: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
cb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
cb40: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
cb50: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
cb60: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
cb70: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
cb80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
cb90: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
cba0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
cbb0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
cbc0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
cbd0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
cbe0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
cbf0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
cc00: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
cc10: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
cc20: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
cc30: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
cc40: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
cc50: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
cc60: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
cc70: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
cc80: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
cc90: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 The xMalloc and
cca0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d xFree methods m
ccb0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 ust work like th
ccc0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e e.** malloc() an
ccd0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
cce0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
ccf0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
cd00: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 ** The xRealloc
cd10: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b method must work
cd20: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 like realloc()
cd30: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
cd40: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 d C library.** w
cd50: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f ith the exceptio
cd60: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65 n that if the se
cd70: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
cd80: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 xRealloc is zer
cd90: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d o,.** xRealloc m
cda0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d ust be a no-op -
cdb0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 it must not per
cdc0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 form any allocat
cdd0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f ion or.** deallo
cde0: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 cation. ^SQLite
cdf0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ce00: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
ce10: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
ce20: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
ce30: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
ce40: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
ce50: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 o xRoundup..** A
ce60: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 nd so in cases w
ce70: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c here xRoundup al
ce80: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 ways returns a p
ce90: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a ositive number,.
cea0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 ** xRealloc can
ceb0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 perform exactly
cec0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 as the standard
ced0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 library realloc(
cee0: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 ) and.** still b
cef0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 e in compliance
cf00: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66 with this specif
cf10: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 ication..**.** x
cf20: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
cf30: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
cf40: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
cf50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
cf60: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
cf70: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
cf80: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
cf90: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
cfa0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
cfb0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
cfc0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
cfd0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
cfe0: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
cff0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
d000: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
d010: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
d020: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
d030: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
d040: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
d050: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
d060: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
d070: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
d080: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
d090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
d0a0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
d0b0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
d0c0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
d0d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
d0e0: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
d0f0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
d100: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
d110: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
d120: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
d130: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
d140: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
d150: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
d160: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
d170: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
d180: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
d190: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
d1a0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
d1b0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
d1c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
d1d0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
d1e0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
d1f0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
d200: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
d210: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (For example,.**
d220: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
d230: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
d240: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
d250: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
d260: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
d270: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
d280: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
d290: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
d2a0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
d2b0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
d2c0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
d2d0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
d2e0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
d2f0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
d300: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
d310: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
d320: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
d330: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
d340: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
d350: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
d360: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
d370: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
d380: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
d390: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
d3a0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
d3b0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
d3c0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
d3d0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
d3e0: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
d3f0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
d400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
d410: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
d420: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
d430: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
d440: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
d450: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
d460: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
d470: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
d480: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
d490: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
d4a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
d4b0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
d4c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
d4d0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
d4e0: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
d4f0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
d500: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
d510: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
d520: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
d530: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
d540: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
d550: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
d560: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
d570: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
d580: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
d590: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
d5a0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
d5b0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
d5c0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
d5d0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
d5e0: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
d5f0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
d600: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
d610: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
d620: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
d630: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
d640: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
d650: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
d660: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
d670: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
d680: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
d690: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
d6a0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
d6b0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
d6c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
d6d0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
d6e0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
d6f0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
d700: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
d710: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
d720: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
d730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
d740: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
d750: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
d760: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
d770: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
d780: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
d790: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
d7a0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
d7b0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
d7c0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
d7d0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
d7e0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
d7f0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
d800: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
d810: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
d820: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
d830: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
d840: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
d850: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
d860: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
d870: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
d880: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
d890: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
d8a0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
d8b0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
d8c0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
d8d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a ion Options.**.*
d8e0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
d8f0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
d900: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
d910: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
d920: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
d930: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
d940: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
d950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
d960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
d970: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
d980: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
d990: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
d9a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
d9b0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
d9c0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
d9d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
d9e0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
d9f0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
da00: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
da10: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
da20: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
da30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 e3_config()] to
da40: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
da50: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
da60: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
da70: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
da80: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
da90: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
daa0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
dab0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
dac0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
dad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
dae0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
daf0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
db00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
db10: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 _SINGLETHREAD</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
db30: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
db40: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
db50: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
db60: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
db70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
db80: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 ingle-thread. I
db90: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
dba0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c t disables.** al
dbb0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 l mutexing and p
dbc0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 uts SQLite into
dbd0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 a mode where it
dbe0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 can only be used
dbf0: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 .** by a single
dc00: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 thread. ^If SQ
dc10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
dc20: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
dc30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
dc40: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
dc50: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
dc60: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
dc70: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
dc80: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 sible to change
dc90: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
dca0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 ode] from its de
dcb0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f fault.** value o
dcc0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 f Single-thread
dcd0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f and so [sqlite3_
dce0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
dcf0: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 eturn .** [SQLIT
dd00: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
dd10: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ed with the SQLI
dd20: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
dd30: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 THREAD.** config
dd40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
dd50: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
dd60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
dd70: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
dd80: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
dd90: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
dda0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
ddb0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
ddc0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
ddd0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
dde0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
ddf0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
de00: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
de10: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
de20: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
de30: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
de40: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
de50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
de60: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
de70: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
de80: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
de90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
dea0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
deb0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
dec0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
ded0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
dee0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
def0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
df00: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
df10: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
df20: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
df30: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
df40: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
df50: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
df60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
df70: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
df80: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
df90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
dfa0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
dfb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
dfc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
dfd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
dfe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
dff0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
e000: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
e010: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
e020: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
e030: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
e040: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
e050: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
e060: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
e070: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
e080: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
e090: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
e0a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
e0b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
e0c0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
e0d0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
e0e0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
e0f0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
e100: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
e110: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
e120: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 ng mode] to Seri
e130: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 alized. In other
e140: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 words, this opt
e150: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
e160: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
e170: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
e180: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
e190: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
e1a0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
e1b0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
e1c0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
e1d0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
e1e0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
e1f0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
e200: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
e210: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
e220: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
e230: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
e240: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
e250: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
e260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e270: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
e280: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
e290: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
e2a0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
e2b0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
e2c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
e2d0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
e2e0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
e2f0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
e300: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
e310: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
e320: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 .** ^If SQLite i
e330: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
e340: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
e350: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
e360: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
e370: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
e380: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
e390: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
e3a0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 to set the Seria
e3b0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
e3c0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
e3d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
e3e0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
e3f0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
e400: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
e410: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
e420: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 SERIALIZED confi
e430: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
e440: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
e450: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
e460: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
e470: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
e480: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
e490: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
e4a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
e4b0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
e4c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
e4d0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
e4e0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
e4f0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
e500: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
e510: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
e520: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
e530: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
e540: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
e550: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
e560: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
e570: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e into SQLite.)^ ^
e580: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 SQLite makes.**
e590: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
e5a0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
e5b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
e5c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
e5d0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 structure.** be
e5e0: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 fore the [sqlite
e5f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 3_config()] call
e600: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a returns.</dd>.*
e610: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
e620: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
e630: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
e640: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
e650: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
e660: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
e670: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
e680: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
e690: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
e6a0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
e6b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d The [sqlite3_m
e6c0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 em_methods].** s
e6d0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
e6e0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
e6f0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 ently defined me
e700: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
e710: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
e720: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
e730: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
e740: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
e750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
e760: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
e770: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 h a wrapper that
e780: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d simulations mem
e790: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
e7a0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 ailure or.** tra
e7b0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 cks memory usage
e7c0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c , for example. <
e7d0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
e7e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
e7f0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c STATUS</dt>.** <
e800: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
e810: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 takes single ar
e820: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
e830: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 nt, interpreted
e840: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e as a .** boolean
e850: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 , which enables
e860: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
e870: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 collection of me
e880: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
e890: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 .** statistics.
e8a0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c ^(When memory al
e8b0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
e8c0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 ics are disabled
e8d0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 , the .** follow
e8e0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 ing SQLite inter
e8f0: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e faces become non
e900: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a -operational:.**
e910: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 <ul>.** <li
e920: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
e930: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c y_used()].** <
e940: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
e950: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
e960: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
e970: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
e980: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c mit64()].** <l
e990: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 i> [sqlite3_stat
e9a0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e us()].** </ul>
e9b0: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c )^.** ^Memory al
e9c0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
e9d0: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 ics are enabled
e9e0: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 by default unles
e9f0: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 s SQLite is.** c
ea00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
ea10: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d LITE_DEFAULT_MEM
ea20: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 STATUS]=0 in whi
ea30: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a ch case memory.*
ea40: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 * allocation sta
ea50: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
ea60: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
ea70: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
ea80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
ea90: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a G_SCRATCH</dt>.*
eaa0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
eab0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
eac0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
ead0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
eae0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
eaf0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
eb00: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
eb10: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 arguments: A p
eb20: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 ointer an 8-byte
eb30: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f .** aligned memo
eb40: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 ry buffer from w
eb50: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20 hich the scrach
eb60: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c allocations will
eb70: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 be.** drawn, th
eb80: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 e size of each s
eb90: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
eba0: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 n (sz),.** and t
ebb0: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
ebc0: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c r of scratch all
ebd0: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 ocations (N). T
ebe0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e he sz.** argumen
ebf0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 t must be a mult
ec00: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 iple of 16..** T
ec10: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
ec20: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e t must be a poin
ec30: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
ec40: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a aligned buffer.
ec50: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 ** of at least s
ec60: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
ec70: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ory..** ^SQLite
ec80: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 will use no more
ec90: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 than two scratc
eca0: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 h buffers per th
ecb0: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 read. So.** N s
ecc0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 hould be set to
ecd0: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 twice the expect
ece0: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 ed maximum numbe
ecf0: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a r of threads..**
ed00: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 ^SQLite will ne
ed10: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 ver require a sc
ed20: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 ratch buffer tha
ed30: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 t is more than 6
ed40: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 .** times the da
ed50: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 tabase page size
ed60: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 . ^If SQLite nee
ed70: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f ds needs additio
ed80: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d nal.** scratch m
ed90: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 emory beyond wha
eda0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 t is provided by
edb0: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 this configurat
edc0: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e ion option, then
edd0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 .** [sqlite3_ma
ede0: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 lloc()] will be
edf0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
ee00: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 he memory needed
ee10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
ee20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
ee30: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a AGECACHE</dt>.**
ee40: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
ee50: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
ee60: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
ee70: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
ee80: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 can use for.** t
ee90: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
eea0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 cache with the
eeb0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 default page cac
eec0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e he implemenation
eed0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
eee0: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 iguration should
eef0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 not be used if
ef00: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
ef10: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 efine page.** ca
ef20: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
ef30: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 on is loaded usi
ef40: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f ng the SQLITE_CO
ef50: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 NFIG_PCACHE opti
ef60: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 on..** There are
ef70: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
ef80: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a to this option:
ef90: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d A pointer to 8-
efa0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 byte aligned.**
efb0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 memory, the size
efc0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 of each page bu
efd0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
efe0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
eff0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 es (N)..** The s
f000: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c z argument shoul
f010: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 d be the size of
f020: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
f030: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 abase page.** (a
f040: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 power of two be
f050: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 tween 512 and 32
f060: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 768) plus a litt
f070: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 le extra for eac
f080: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 h.** page header
f090: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 . ^The page hea
f0a0: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 der size is 20 t
f0b0: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e o 40 bytes depen
f0c0: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 ding on.** the h
f0d0: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 ost architecture
f0e0: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 . ^It is harmle
f0f0: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 ss, apart from t
f100: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 he wasted memory
f110: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 ,.** to make sz
f120: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 a little too lar
f130: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ge. The first.*
f140: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
f150: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
f160: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
f170: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
f180: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
f190: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
f1a0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 he memory provid
f1b0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
f1c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 argument to sati
f1d0: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 sfy its.** memor
f1e0: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 y needs for the
f1f0: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 first N pages th
f200: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 at it adds to ca
f210: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 che. ^If additi
f220: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 onal.** page cac
f230: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 he memory is nee
f240: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ded beyond what
f250: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
f260: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e his option, then
f270: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 .** SQLite goes
f280: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
f290: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 oc()] for the ad
f2a0: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 ditional storage
f2b0: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 space..** The p
f2c0: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 ointer in the fi
f2d0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
f2e0: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 t.** be aligned
f2f0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
f300: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
f310: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
f320: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 SQLite.** will b
f330: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 e undefined.</dd
f340: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
f350: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
f360: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
f370: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
f380: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
f390: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
f3a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
f3b0: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 * for all of its
f3c0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
f3d0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
f3e0: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 beyond those pr
f3f0: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 ovided.** for by
f400: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
f410: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 SCRATCH] and [SQ
f420: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
f430: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 CACHE]..** There
f440: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
f450: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 ents: An 8-byte
f460: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 aligned pointer
f470: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a to the memory,.*
f480: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
f490: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
f4a0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
f4b0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
f4c0: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 cation size..**
f4d0: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f ^If the first po
f4e0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
f4f0: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
f500: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
f510: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
f520: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
f530: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
f540: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
f550: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
f560: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
f570: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
f580: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
f590: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
f5a0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 . ^If the.** me
f5b0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 mory pointer is
f5c0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 not NULL and eit
f5d0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 her [SQLITE_ENAB
f5e0: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a LE_MEMSYS3] or.*
f5f0: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
f600: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 _MEMSYS5] are de
f610: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 fined, then the
f620: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
f630: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 ry.** allocator
f640: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 is engaged to ha
f650: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 ndle all of SQLi
f660: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tes memory alloc
f670: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 ation needs..**
f680: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 The first pointe
f690: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
f6a0: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 inter) must be a
f6b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
f6c0: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 yte.** boundary
f6d0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 or subsequent be
f6e0: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 havior of SQLite
f6f0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
f700: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
f710: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
f720: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c _MUTEX</dt>.** <
f730: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
f740: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
f750: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
f760: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
f770: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
f780: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
f790: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
f7a0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
f7b0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
f7c0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
f7d0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 low-level mutex
f7e0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 routines to be u
f7f0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 sed in place.**
f800: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e the mutex routin
f810: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
f820: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 Lite.)^ ^SQLite
f830: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
f840: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 the.** content
f850: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
f860: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
f870: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 tructure before
f880: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b the call to.** [
f890: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f8a0: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 ] returns. ^If S
f8b0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
f8c0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
f8d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
f8e0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
f8f0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
f900: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
f910: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d .** the entire m
f920: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 utexing subsyste
f930: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f m is omitted fro
f940: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 m the build and
f950: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a hence calls to.*
f960: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
f970: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 g()] with the SQ
f980: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
f990: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 X configuration
f9a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 option will.** r
f9b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
f9c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ROR].</dd>.**.**
f9d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
f9e0: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
f9f0: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
fa00: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
fa10: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
fa20: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
fa30: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
fa40: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
fa50: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
fa60: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
fa70: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
fa80: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
fa90: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
faa0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
fab0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
fac0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 mutex routines.)
fad0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
fae0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
faf0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
fb00: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
fb10: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
fb20: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
fb30: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
fb40: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
fb50: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
fb60: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
fb70: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
fb80: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
fb90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
fba0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
fbb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
fbc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
fbd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
fbe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
fbf0: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
fc00: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
fc10: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
fc20: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
fc30: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
fc40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
fc50: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
fc60: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e FIG_GETMUTEX con
fc70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
fc80: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
fc90: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
fca0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
fcb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
fcc0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
fcd0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
fce0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
fcf0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
fd00: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c rmine the defaul
fd10: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t.** memory allo
fd20: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c cation for the l
fd30: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
fd40: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 allocator on eac
fd50: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 h.** [database c
fd60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
fd70: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
fd80: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
fd90: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
fda0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
fdb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
fdc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
fdd0: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 slots allocated
fde0: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
fdf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 connection.)^
fe00: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^(This option se
fe10: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 ts the.** <i>def
fe20: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 ault</i> lookasi
fe30: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 de size. The [SQ
fe40: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
fe50: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 OKASIDE].** verb
fe60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
fe70: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 config()] can be
fe80: 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
fe90: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
fea0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
feb0: 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e n individual con
fec0: 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 nections.)^ </dd
fed0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
fee0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
fef0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
ff00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
ff10: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
ff20: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
ff30: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 ointer to.** an
ff40: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
ff50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
ff60: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
ff70: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 ecifies the inte
ff80: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 rface.** to a cu
ff90: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
ffa0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 implementation.)
ffb0: 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
ffc0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
ffd0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 * object and use
ffe0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 s it for page ca
fff0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
10000 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ations.</dd>.**.
10010 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
10020 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f NFIG_GETPCACHE</
10030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
10040 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
10050 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
10060 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
10070 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
10080 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
10090 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
100a0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 SQLite copies of
100b0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
100c0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
100d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 mentation into t
100e0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f hat object.)^ </
100f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
10100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c LITE_CONFIG_LOG<
10110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
10130 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOG option takes
10140 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 two arguments:
10150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a a pointer to a.*
10160 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 * function with
10170 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 a call signature
10180 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 of void(*)(void
10190 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
101a0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f *), .** and a po
101b0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e inter to void. ^
101c0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
101d0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
101e0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e ULL, it is.** in
101f0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 voked by [sqlite
10200 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 3_log()] to proc
10210 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 ess each logging
10220 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 event. ^If the
10230 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 .** function poi
10240 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 nter is NULL, th
10250 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 e [sqlite3_log()
10260 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f ] interface beco
10270 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 mes a no-op..**
10280 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 ^The void pointe
10290 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 r that is the se
102a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
102b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
102c0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 OG is.** passed
102d0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
102e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
102f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
10300 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
10310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 .** function whe
10320 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 never that funct
10330 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ion is invoked.
10340 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
10350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
10360 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
10370 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
10380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
10390 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 r to the corresp
103a0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 onding.** [sqlit
103b0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 e3_log()] call a
103c0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 nd is intended t
103d0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 o be a [result c
103e0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 ode] or an.** [e
103f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
10400 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 ode]. ^The thir
10410 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 d parameter pass
10420 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 ed to the logger
10430 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 is.** log messa
10440 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 ge after formatt
10450 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ing via [sqlite3
10460 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a _snprintf()]..**
10470 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 The SQLite logg
10480 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 ing interface is
10490 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 not reentrant;
104a0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
104b0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 ion.** supplied
104c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
104d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f on must not invo
104e0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e ke any SQLite in
104f0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 terface..** In a
10500 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 multi-threaded
10510 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 application, the
10520 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
10530 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 ined logger.** f
10540 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 unction must be
10550 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 threadsafe. </dd
10560 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
10570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
10580 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
10590 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
105a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
105b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
105c0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
105d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
105e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
105f0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
10600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
10610 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
10620 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
10630 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
10640 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
10650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
10660 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
10670 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
10680 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
10690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
106a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
106b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
106c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
106d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
106e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
106f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
10700 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
10710 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
10720 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
10730 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
10740 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
10750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
10760 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
10770 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
10780 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
10790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
107a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
107b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
107c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
107d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
107e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
107f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
10800 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
10810 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
10820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
10830 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
10840 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
10850 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
10860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
10870 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
10880 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
10890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
108a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
108b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
108c0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
108d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
108e0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 IG_GETPCACHE
108f0 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 15 /* sqlite3_p
10900 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a cache_methods* *
10910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10920 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 _CONFIG_LOG
10930 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 16 /* xFun
10940 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a c, void* */../*.
10950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
10960 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
10970 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
10980 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ptions.**.** The
10990 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
109a0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
109b0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
109c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
109d0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
109e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
109f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
10a00 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
10a10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
10a20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
10a30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10a40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
10a50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
10a60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
10a70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
10a80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
10a90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
10aa0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
10ab0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
10ac0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
10ad0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
10ae0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 3_db_config()] t
10af0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
10b00 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
10b10 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 ked. ^The [sqli
10b20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
10b30 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
10b40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
10b50 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
10b60 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
10b70 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
10b80 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
10b90 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
10ba0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
10bb0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
10bc0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
10bd0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
10be0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b ^This option tak
10bf0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f es three additio
10c00 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 nal arguments th
10c10 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
10c20 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 .** [lookaside
10c30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
10c40 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
10c50 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 for the [databas
10c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
10c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
10c80 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 ument (the third
10c90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
10ca0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
10cb0 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ()] is a.** poin
10cc0 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 ter to an memory
10cd0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
10ce0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
10cf0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
10d00 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
10d10 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
10d20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
10d30 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
10d40 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
10d50 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
10d60 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
10d70 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
10d80 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
10d90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
10da0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
10db0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
10dc0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
10dd0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
10de0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
10df0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
10e00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
10e10 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
10e20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
10e30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
10e40 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
10e50 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
10e60 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
10e70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
10e80 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
10e90 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
10ea0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
10eb0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
10ec0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
10ed0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
10ee0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
10ef0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
10f00 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
10f10 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
10f20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
10f30 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
10f40 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
10f50 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
10f60 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
10f70 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
10f80 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
10f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10fa0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
10fb0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
10fc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
10fd0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
10fe0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
10ff0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
11000 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
11010 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
11020 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
11030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
11040 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
11050 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
11060 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
11070 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
11080 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
11090 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
110a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
110b0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
110c0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
110d0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
110e0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
110f0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
11100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
11110 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
11120 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
11130 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
11140 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 _LOOKASIDE 10
11150 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 01 /* void* int
11160 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int */.../*.**
11170 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
11180 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
11190 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
111a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
111b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
111c0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
111d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
111e0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
111f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
11200 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
11210 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 of SQLite. ^The
11220 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
11230 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
11240 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
11250 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
11260 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
11270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
11280 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
11290 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
112a0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
112b0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
112c0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a Insert Rowid.**.
112d0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 ** ^Each entry i
112e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
112f0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
11300 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
11310 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
11320 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
11330 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
11340 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
11350 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
11360 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
11370 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
11380 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
11390 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
113a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
113b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
113c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
113d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
113e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
113f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
11400 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
11410 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
11420 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
11430 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
11440 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
11450 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
11460 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f returns the [ro
11470 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 wid] of the most
11480 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 recent.** succe
11490 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
114a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
114b0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 from the [datab
114c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
114d0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
114e0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e argument. ^If n
114f0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
11500 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 SERT]s.** have e
11510 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 ver occurred on
11520 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f that database co
11530 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 nnection, zero i
11540 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
11550 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 * ^(If an [INSER
11560 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
11570 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e a trigger, then
11580 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
11590 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
115a0 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
115b0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
115c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
115d0 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e rigger is runnin
115e0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
115f0 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
11600 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
11610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
11620 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 s routine.** rev
11630 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
11640 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
11650 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
11660 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a er fired.)^.**.*
11670 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 * ^An [INSERT] t
11680 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
11690 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
116a0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
116b0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
116c0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 INSERT] and does
116d0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
116e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
116f0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
11700 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 e. ^Thus INSERT
11710 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 OR FAIL, INSERT
11720 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 OR IGNORE, INSE
11730 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a RT OR ROLLBACK,.
11740 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 ** and INSERT OR
11750 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 ABORT make no c
11760 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 hanges to the re
11770 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
11780 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 is.** routine wh
11790 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 en their inserti
117a0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 on fails. ^(Whe
117b0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c n INSERT OR REPL
117c0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ACE.** encounter
117d0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 s a constraint v
117e0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 iolation, it doe
117f0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 s not fail. The
11800 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 .** INSERT conti
11810 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
11820 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e on after deletin
11830 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 g rows that caus
11840 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 ed.** the constr
11850 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 aint problem so
11860 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
11870 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 E will always ch
11880 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 ange.** the retu
11890 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
118a0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a interface.)^.**
118b0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 .** ^For the pur
118c0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
118d0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
118e0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
118f0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
11900 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
11910 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
11920 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
11930 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
11940 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 is accessible t
11950 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
11960 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 via the.** [las
11970 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
11980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
11990 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
119a0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f ate thread perfo
119b0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 rms a new [INSER
119c0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a T] on the same.*
119d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
119e0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 ction while the
119f0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
11a00 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a sert_rowid()].**
11a10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
11a20 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 ning and thus ch
11a30 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 anges the last i
11a40 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a nsert [rowid],.*
11a50 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 * then the value
11a60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
11a70 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
11a80 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a t_rowid()] is.**
11a90 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
11aa0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 nd might not equ
11ab0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c al either the ol
11ac0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 d or the new.**
11ad0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
11ae0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f id]..*/.sqlite3_
11af0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 int64 sqlite3_la
11b00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
11b10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
11b20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e * CAPI3REF: Coun
11b30 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 t The Number Of
11b40 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
11b50 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
11b60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
11b70 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
11b80 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 e rows that were
11b90 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 changed.** or i
11ba0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
11bb0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
11bc0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
11bd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a d SQL statement.
11be0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ** on the [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11c00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
11c10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
11c20 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e ..** ^(Only chan
11c30 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 ges that are dir
11c40 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 ectly specified
11c50 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c by the [INSERT],
11c60 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 [UPDATE],.** or
11c70 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
11c80 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e ent are counted.
11c90 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e Auxiliary chan
11ca0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a ges caused by.**
11cb0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f triggers or [fo
11cc0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
11cd0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 s] are not count
11ce0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a ed.)^ Use the.**
11cf0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
11d00 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
11d10 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ion to find the
11d20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
11d30 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 changes.** inclu
11d40 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 ding changes cau
11d50 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 sed by triggers
11d60 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 and foreign key
11d70 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e actions..**.** ^
11d80 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
11d90 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c w that are simul
11da0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 ated by an [INST
11db0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a EAD OF trigger].
11dc0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
11dd0 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 ed. Only real t
11de0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 able changes are
11df0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
11e00 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 ^(A "row change"
11e10 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 is a change to
11e20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 a single row of
11e30 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a a single table.*
11e40 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 * caused by an I
11e50 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f NSERT, DELETE, o
11e60 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 r UPDATE stateme
11e70 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a nt. Rows that.*
11e80 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 * are changed as
11e90 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 side effects of
11ea0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
11eb0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
11ec0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
11ed0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
11ee0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f [DROP TABLE], o
11ef0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a r by any other.*
11f00 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 * mechanisms do
11f10 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 not count as dir
11f20 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e ect row changes.
11f30 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 )^.**.** A "trig
11f40 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 ger context" is
11f50 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 a scope of execu
11f60 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 tion that begins
11f70 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 and.** ends wit
11f80 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 h the script of
11f90 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 a [CREATE TRIGGE
11fa0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a R | trigger]. .*
11fb0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 * Most SQL state
11fc0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 ments are.** eva
11fd0 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f luated outside o
11fe0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 f any trigger.
11ff0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 This is the "top
12000 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 level".** trigg
12010 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 er context. If
12020 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 a trigger fires
12030 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
12040 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 el, a.** new tri
12050 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 gger context is
12060 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 entered for the
12070 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 duration of that
12080 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e one.** trigger.
12090 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 Subtriggers cr
120a0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 eate subcontexts
120b0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 for their durat
120c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ion..**.** ^Call
120d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 ing [sqlite3_exe
120e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
120f0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 _step()] recursi
12100 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 vely does.** not
12110 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 create a new tr
12120 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
12130 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
12140 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
12150 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 number of direct
12160 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 row changes in
12170 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 the.** most rece
12180 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
12190 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 E, or DELETE sta
121a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
121b0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 e same.** trigge
121c0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
121d0 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c ^Thus, when cal
121e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 led from the top
121f0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e level, this fun
12200 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
12210 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
12220 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
12230 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
12240 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
12250 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f ETE.** that also
12260 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 occurred at the
12270 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 top level. ^(W
12280 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
12290 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 f a trigger,.**
122a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
122b0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 ges() interface
122c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f can be called to
122d0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
122e0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 of.** changes i
122f0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
12300 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e tly completed IN
12310 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
12320 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 DELETE.** state
12330 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
12340 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 body of the same
12350 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 trigger..** How
12360 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 ever, the number
12370 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e returned does n
12380 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
12390 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 es.** caused by
123a0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 subtriggers sinc
123b0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 e those have the
123c0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 ir own context.)
123d0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
123e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
123f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
12400 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
12410 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
12420 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
12430 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
12440 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
12450 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
12460 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
12470 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
12480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12490 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
124a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
124b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
124c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
124d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
124e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
124f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
12500 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
12510 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
12520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
12530 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
12540 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
12550 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
12560 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
12570 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e mber of row chan
12580 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 ges caused by [I
12590 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 NSERT],.** [UPDA
125a0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
125b0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 statements since
125c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
125d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f onnection] was o
125e0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 pened..** ^(The
125f0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 count returned b
12600 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
12610 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 changes() includ
12620 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a es all changes.*
12630 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 * from all [CREA
12640 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
12650 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 gger] contexts a
12660 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 nd changes made
12670 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b by.** [foreign k
12680 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 ey actions]. How
12690 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 ever,.** the cou
126a0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
126b0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 ude changes used
126c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 to implement [R
126d0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
126e0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 nts,.** do rollb
126f0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 acks or ABORT pr
12700 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 ocessing, or [DR
12710 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 OP TABLE] proces
12720 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f sing. The.** co
12730 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
12740 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 lude rows of vie
12750 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 ws that fire an
12760 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
12770 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 ger],.** though
12780 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f if the INSTEAD O
12790 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 F trigger makes
127a0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f changes of its o
127b0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 wn, those change
127c0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 s .** are counte
127d0 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c d.)^.** ^The sql
127e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
127f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f es() function co
12800 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 unts the changes
12810 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 as soon as.** t
12820 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
12830 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 t makes them is
12840 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
12850 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
12860 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 ndle.** is passe
12870 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
12880 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
12890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
128a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
128b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
128c0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
128d0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
128e0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
128f0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
12900 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
12910 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
12920 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
12930 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
12940 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
12950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12960 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
12970 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
12980 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
12990 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
129a0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
129b0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
129c0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
129d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
129e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
129f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
12a00 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
12a10 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
12a20 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e ng Query.**.** ^
12a30 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
12a40 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 uses any pending
12a50 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
12a60 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 ion to abort and
12a70 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 .** return at it
12a80 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 s earliest oppor
12a90 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 tunity. This rou
12aa0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c tine is typicall
12ab0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 y.** called in r
12ac0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 esponse to a use
12ad0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 r action such as
12ae0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 pressing "Cance
12af0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 l".** or Ctrl-C
12b00 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 where the user w
12b10 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 ants a long quer
12b20 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 y operation to h
12b30 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 alt.** immediate
12b40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ly..**.** ^It is
12b50 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
12b60 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 is routine from
12b70 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 a thread differe
12b80 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 nt from the.** t
12b90 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 hread that is cu
12ba0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 rrently running
12bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 the database ope
12bc0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a ration. But it.
12bd0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 ** is not safe t
12be0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
12bf0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 ine with a [data
12c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12c10 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 that.** is clos
12c20 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 ed or might clos
12c30 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 e before sqlite3
12c40 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
12c50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 urns..**.** ^If
12c60 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
12c70 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
12c80 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
12c90 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
12ca0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
12cb0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
12cc0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
12cd0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
12ce0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
12cf0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
12d00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
12d10 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e pletion..**.** ^
12d20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
12d30 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
12d40 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
12d50 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
12d60 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 PT]..** ^If the
12d70 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
12d80 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
12d90 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
12da0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
12db0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
12dc0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
12dd0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
12de0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
12df0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
12e00 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
12e10 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cally..**.** ^Th
12e20 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
12e30 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 upt(D) call is i
12e40 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 n effect until a
12e50 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e ll currently run
12e60 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
12e70 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 ements on [datab
12e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12e90 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e D complete. ^An
12ea0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
12eb0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
12ec0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
12ed0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
12ee0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
12ef0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
12f00 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
12f10 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
12f20 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
12f30 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
12f40 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
12f50 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
12f60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
12f70 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 all. ^New SQL s
12f80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
12f90 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
12fa0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 ter the running
12fb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 statement count
12fc0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
12fd0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 .** not effected
12fe0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
12ff0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 interrupt()..**
13000 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ^A call to sqlit
13010 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
13020 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e that occurs when
13030 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 there are no ru
13040 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
13050 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d tements is a no-
13060 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 op and has no ef
13070 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
13080 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
13090 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
130a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
130b0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 errupt() call re
130c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 turns..**.** If
130d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
130e0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 nection closes w
130f0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e hile [sqlite3_in
13100 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 terrupt()].** is
13110 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 running then ba
13120 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 d things will li
13130 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a kely happen..*/.
13140 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
13150 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
13160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13170 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
13180 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
13190 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
131a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
131b0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
131c0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
131d0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
131e0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
131f0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
13200 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
13210 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
13220 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
13230 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
13240 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
13250 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
13260 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
13270 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
13280 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
13290 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
132a0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
132b0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
132c0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
132d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
132e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
132f0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
13300 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
13310 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
13320 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
13330 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
13340 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
13350 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
13360 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
13370 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
13380 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
13390 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
133a0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
133b0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
133c0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
133d0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
133e0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
133f0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
13400 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
13410 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
13420 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
13430 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
13440 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
13450 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
13460 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
13470 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
13480 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
13490 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
134a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
134b0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
134c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
134d0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
134e0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
134f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
13500 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
13510 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
13520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
13530 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
13540 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
13550 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
13560 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
13570 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
13580 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
13590 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
135a0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
135b0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
135c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
135d0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
135e0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
135f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
13600 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
13610 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
13620 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
13630 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
13640 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
13650 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
13660 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
13670 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
13680 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
13690 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
136a0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
136b0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
136c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
136d0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
136e0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
136f0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
13700 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
13710 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
13720 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
13730 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
13740 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
13750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
13760 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
13770 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
13780 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
13790 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
137a0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e yte order..*/.in
137b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
137c0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
137d0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
137e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
137f0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
13800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
13810 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
13820 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
13830 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
13840 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
13850 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
13860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
13870 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
13880 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
13890 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
138a0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
138b0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
138c0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
138d0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
138e0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
138f0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
13900 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
13910 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
13920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
13930 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
13940 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
13950 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
13960 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
13970 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
13980 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
13990 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
139a0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
139b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
139c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
139d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
139e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
139f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
13a00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
13a10 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
13a20 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
13a30 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
13a40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
13a50 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
13a60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
13a70 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
13a80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
13a90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
13aa0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
13ab0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
13ac0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
13ad0 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
13ae0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
13af0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
13b00 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
13b10 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
13b20 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
13b30 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
13b40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
13b50 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
13b60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
13b70 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
13b80 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
13b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
13ba0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
13bb0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
13bc0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
13bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
13be0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
13bf0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
13c00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
13c10 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
13c20 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
13c30 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
13c40 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
13c50 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
13c60 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
13c70 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
13c80 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
13c90 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
13ca0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
13cb0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
13cc0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
13cd0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
13ce0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
13cf0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
13d00 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
13d10 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
13d20 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
13d30 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
13d40 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
13d50 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
13d60 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
13d70 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
13d80 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
13d90 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
13da0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
13db0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
13dc0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
13dd0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
13de0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
13df0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
13e00 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
13e10 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
13e20 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
13e30 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
13e40 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
13e50 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
13e60 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
13e70 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
13e80 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
13e90 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
13ea0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
13eb0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
13ec0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
13ed0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
13ee0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
13ef0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
13f00 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
13f10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
13f20 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
13f30 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
13f40 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
13f50 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
13f60 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
13f70 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
13f80 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
13f90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
13fa0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
13fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
13fc0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
13fd0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
13fe0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
13ff0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
14000 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
14010 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
14020 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
14030 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
14040 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
14050 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
14060 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
14070 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
14080 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
14090 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
140a0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
140b0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
140c0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
140d0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
140e0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
140f0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
14100 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
14110 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
14120 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
14130 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
14140 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
14150 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
14160 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
14170 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
14180 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
14190 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
141a0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
141b0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
141c0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
141d0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
141e0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
141f0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
14200 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
14210 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
14220 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
14230 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
14240 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
14250 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
14260 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
14270 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
14280 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
14290 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
142a0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
142b0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
142c0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
142d0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
142e0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
142f0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
14300 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
14310 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
14320 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
14330 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
14340 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
14350 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
14360 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
14370 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
14380 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
14390 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
143a0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
143b0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
143c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
143d0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
143e0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
143f0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
14400 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
14410 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
14420 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
14430 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
14440 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
14450 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
14460 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
14470 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
14480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14490 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
144a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
144b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
144c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
144d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
144e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
144f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
14500 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
14510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14520 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
14530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
14540 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
14550 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 sy handler..*/.i
14560 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
14570 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
14580 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
14590 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
145a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
145b0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
145c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
145d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
145e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
145f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
14600 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
14610 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
14620 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
14630 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
14640 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
14650 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
14660 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
14670 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
14680 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
14690 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
146a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
146b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
146c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
146d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
146e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
146f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
14700 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
14710 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
14720 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
14730 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
14740 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
14750 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
14760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
14770 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
14780 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
14790 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
147a0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
147b0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
147c0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
147d0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
147e0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
147f0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
14800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14810 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 on] any any give
14820 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
14830 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
14840 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
14850 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
14860 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
14870 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
14880 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
14890 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
148a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
148b0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 cleared.)^.*/.i
148c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
148d0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
148e0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
148f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
14900 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
14910 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
14920 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ries.**.** This
14930 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
14940 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
14950 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
14960 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
14970 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
14980 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
14990 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
149a0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
149b0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
149c0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
149d0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
149e0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
149f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
14a00 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
14a10 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
14a20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
14a30 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
14a40 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
14a50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
14a60 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
14a70 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
14a80 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
14a90 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
14aa0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
14ab0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
14ac0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
14ad0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
14ae0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
14af0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
14b00 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
14b10 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
14b20 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
14b30 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
14b40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
14b50 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
14b60 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
14b70 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
14b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
14b90 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
14ba0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
14bb0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
14bc0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
14bd0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
14be0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
14bf0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
14c00 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
14c10 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
14c20 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
14c30 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
14c40 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
14c50 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
14c60 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
14c70 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
14c80 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
14c90 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
14ca0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
14cb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
14cc0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
14cd0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
14ce0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
14cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
14d00 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
14d10 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
14d20 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
14d30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
14d40 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
14d50 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
14d60 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
14d70 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
14d80 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
14d90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
14da0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
14db0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
14dc0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
14dd0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
14de0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
14df0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
14e00 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
14e10 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
14e20 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
14e30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
14e40 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
14e50 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
14e60 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
14e70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14e80 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
14e90 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
14ea0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
14eb0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
14ec0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
14ed0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
14ee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
14ef0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
14f00 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
14f10 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
14f20 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
14f30 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
14f40 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
14f50 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
14f60 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
14f70 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
14f80 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
14f90 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
14fa0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
14fb0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
14fc0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
14fd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
14fe0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
14ff0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
15000 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
15010 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
15020 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
15030 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
15040 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
15050 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
15060 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
15070 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
15080 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
15090 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
150a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
150b0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
150c0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
150d0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
150e0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
150f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
15100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
15110 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
15120 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
15130 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
15140 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
15150 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
15160 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
15170 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
15180 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
15190 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
151a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
151b0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
151c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
151d0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
151e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
151f0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
15200 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
15210 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
15220 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
15230 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
15240 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
15250 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
15260 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
15270 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
15280 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
15290 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
152a0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
152b0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
152c0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
152d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
152e0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
152f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
15300 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
15310 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
15320 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
15330 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
15340 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
15350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
15360 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
15370 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
15380 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
15390 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
153a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
153b0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
153c0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
153d0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
153e0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
153f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
15400 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
15410 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
15420 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
15430 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
15440 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
15450 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
15460 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
15470 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
15480 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
15490 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
154a0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
154b0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
154c0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
154d0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
154e0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
154f0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
15500 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
15510 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
15520 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
15530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
15540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
15550 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e errmsg()]..*/.in
15560 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
15570 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
15580 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
15590 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
155a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
155b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
155c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
155d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
155e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
155f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
15600 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
15610 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
15620 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
15630 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
15640 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
15650 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
15660 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
15670 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
15680 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
15690 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
156a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
156b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
156c0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
156d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
156e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
156f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
15700 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
15710 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
15720 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
15730 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
15740 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
15750 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
15760 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
15770 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
15780 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
15790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
157a0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
157b0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
157c0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
157d0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
157e0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
157f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
15800 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
15810 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
15820 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
15830 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
15840 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
15850 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
15860 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
15870 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
15880 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
15890 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
158a0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
158b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
158c0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
158d0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
158e0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
158f0 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f ** ^(In sqlite3_
15900 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
15910 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
15920 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
15930 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
15940 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
15950 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
15960 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
15970 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
15980 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
15990 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
159a0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
159b0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
159c0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
159d0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
159e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
159f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
15a00 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
15a10 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
15a20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
15a30 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
15a40 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
15a50 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
15a60 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
15a70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
15a80 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
15a90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
15aa0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
15ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
15ac0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
15ad0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
15ae0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
15af0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
15b00 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
15b10 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
15b20 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
15b30 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
15b40 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
15b50 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
15b60 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
15b70 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
15b80 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
15b90 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
15ba0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
15bb0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
15bc0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
15bd0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
15be0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
15bf0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
15c00 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
15c10 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
15c20 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
15c30 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
15c40 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
15c50 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
15c60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
15c70 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
15c80 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
15c90 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
15ca0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
15cb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
15cc0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
15cd0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
15ce0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
15cf0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
15d00 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
15d10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
15d20 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
15d30 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
15d40 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
15d50 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
15d60 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
15d70 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
15d80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
15d90 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
15da0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
15db0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
15dc0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
15dd0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
15de0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
15df0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
15e00 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
15e10 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
15e20 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
15e30 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 titutes a null-t
15e40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
15e50 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 ing from the arg
15e60 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 ument list. But
15e70 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 %q also doubles
15e80 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 every '\'' char
15e90 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 acter..** %q is
15ea0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 designed for use
15eb0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 inside a string
15ec0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 literal.)^ By
15ed0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
15ee0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
15ef0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
15f00 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
15f10 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
15f20 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
15f30 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
15f40 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
15f50 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
15f60 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
15f70 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
15f80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
15f90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
15fa0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
15fb0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
15fc0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
15fd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
15fe0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
15ff0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
16000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
16010 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
16020 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
16030 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
16040 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
16050 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
16060 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
16070 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
16080 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
16090 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
160a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
160b0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
160c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
160d0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
160e0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
160f0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
16100 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
16110 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
16120 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
16130 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
16140 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
16150 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
16160 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
16170 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
16180 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
16190 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
161a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
161b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
161c0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
161d0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
161e0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
161f0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
16200 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
16210 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
16220 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
16230 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
16240 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
16250 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
16260 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
16270 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
16280 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
16290 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
162a0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
162b0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
162c0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
162d0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
162e0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
162f0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
16300 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
16310 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ral..**.** ^(The
16320 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
16330 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
16340 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
16350 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
16360 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
16370 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
16380 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
16390 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
163a0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
163b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
163c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
163d0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
163e0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
163f0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
16400 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 le quotes).)^ S
16410 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 o, for example,
16420 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a one could say:.*
16430 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
16440 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
16450 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
16460 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
16470 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
16480 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a S(%Q)", zText);.
16490 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
164a0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
164b0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
164c0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
164d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
164e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f te>.**.** The co
164f0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 de above will re
16500 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 nder a correct S
16510 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
16520 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 the zSQL.** vari
16530 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 able even if the
16540 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 zText variable
16550 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
16560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 r..**.** ^(The "
16570 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
16580 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
16590 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
165a0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
165b0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
165c0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
165d0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
165e0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
165f0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
16600 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
16610 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
16620 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c .)^.*/.char *sql
16630 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
16640 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 st char*,...);.c
16650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
16660 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
16670 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 *, va_list);.cha
16680 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
16690 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
166a0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
166b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
166c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
166d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
166e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
166f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
16700 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
16710 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
16720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
16730 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
16740 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
16750 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
16760 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
16770 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
16780 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
16790 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
167a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
167b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
167c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
167d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
167e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
167f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
16800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
16810 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
16820 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
16830 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
16840 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
16850 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
16860 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
16870 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
16880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
16890 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
168a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
168b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
168c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
168d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
168e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
168f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
16900 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
16910 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
16920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
16930 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
16940 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ointer..**.** ^C
16950 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
16960 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
16970 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
16980 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
16990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
169a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
169b0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
169c0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
169d0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
169e0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 reused. ^The s
169f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
16a00 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
16a10 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
16a20 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
16a30 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
16a40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
16a50 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
16a60 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
16a70 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
16a80 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
16a90 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
16aa0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
16ab0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
16ac0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
16ad0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
16ae0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
16af0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
16b00 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
16b10 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
16b20 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
16b30 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
16b40 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
16b50 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
16b60 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
16b70 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
16b80 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
16b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
16ba0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
16bb0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
16bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
16bd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
16be0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
16bf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
16c00 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
16c10 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
16c20 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
16c30 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
16c40 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
16c50 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
16c60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
16c70 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
16c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
16c90 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
16ca0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
16cb0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 eter.)^ ^ If the
16cc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
16cd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
16ce0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
16cf0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
16d00 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
16d10 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
16d20 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
16d30 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
16d40 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
16d50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
16d60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
16d70 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e ** ^If the secon
16d80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
16d90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
16da0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
16db0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
16dc0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
16dd0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
16de0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
16df0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 te3_free(P) wher
16e00 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 e P is the first
16e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
16e20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
16e30 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 .** ^sqlite3_rea
16e40 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
16e50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
16e60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
16e70 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
16e80 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
16e90 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
16ea0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
16eb0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e navailable..** ^
16ec0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 If M is the size
16ed0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
16ee0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d location, then m
16ef0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a in(N,M) bytes.**
16f00 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c of the prior al
16f10 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 location are cop
16f20 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 ied into the beg
16f30 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 inning of buffer
16f40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
16f50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
16f60 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
16f70 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
16f80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
16f90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
16fa0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e turns NULL, then
16fb0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
16fc0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 ation.** is not
16fd0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 freed..**.** ^Th
16fe0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
16ff0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
17000 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 loc() and sqlite
17010 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
17020 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
17030 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
17040 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 8 byte boundary,
17050 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 or to a.** 4 by
17060 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 te boundary if t
17070 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 he [SQLITE_4_BYT
17080 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 E_ALIGNED_MALLOC
17090 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
170a0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 * option is used
170b0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
170c0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
170d0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
170e0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
170f0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
17100 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
17110 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
17120 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
17130 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
17140 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
17150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
17160 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
17170 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
17180 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
17190 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
171a0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
171b0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
171c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 sed..**.** The W
171d0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
171e0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a ace layer calls.
171f0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 ** the system ma
17200 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
17210 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 ) directly when
17220 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 converting.** fi
17230 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 lenames between
17240 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 the UTF-8 encodi
17250 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 ng used by SQLit
17260 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 e.** and whateve
17270 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 r filename encod
17280 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 ing is used by t
17290 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 he particular Wi
172a0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c ndows.** install
172b0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 ation. Memory a
172c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 llocation errors
172d0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 are detected, b
172e0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 ut.** they are r
172f0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
17300 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
17310 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
17320 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
17330 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
17340 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
17350 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
17360 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
17370 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
17380 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
17390 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
173a0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
173b0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
173c0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
173d0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
173e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
173f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
17400 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
17410 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
17420 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
17430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
17440 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
17450 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
17460 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
17470 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
17480 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
17490 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
174a0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
174b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
174c0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 ]..*/.void *sqli
174d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
174e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 .void *sqlite3_r
174f0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
17500 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
17510 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
17520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
17530 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
17540 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
17550 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
17560 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
17570 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
17580 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
17590 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
175a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
175b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
175c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
175d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
175e0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
175f0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
17600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
17610 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
17620 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
17630 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
17640 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
17650 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
17660 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
17670 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
17680 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
17690 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
176a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
176b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
176c0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
176d0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
176e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
176f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
17700 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
17710 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
17720 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
17730 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
17740 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
17750 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
17760 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
17770 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
17780 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
17790 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
177a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
177b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
177c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
177d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
177e0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
177f0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
17800 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
17810 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
17820 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
17830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
17840 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
17850 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
17860 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
17870 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
17880 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
17890 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
178a0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
178b0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
178c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
178d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
178e0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
178f0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
17900 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
17910 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
17920 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
17930 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
17940 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
17950 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 reset..*/.sqlite
17960 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
17970 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
17980 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
17990 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
179a0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
179b0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
179c0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 CAPI3REF: Pseud
179d0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 o-Random Number
179e0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 Generator.**.**
179f0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
17a00 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
17a10 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
17a20 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
17a30 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
17a40 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
17a50 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
17a60 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
17a70 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
17a80 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
17a90 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
17aa0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
17ab0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
17ac0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
17ad0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
17ae0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
17af0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
17b00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
17b10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
17b20 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
17b30 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
17b40 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
17b50 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
17b60 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 .**.** ^A call t
17b70 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
17b80 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
17b90 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
17ba0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
17bb0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
17bc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
17bd0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 invoked (either
17be0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 internally or b
17bf0 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 y.** the applica
17c00 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 tion) the PRNG i
17c10 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 s seeded using r
17c20 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
17c30 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 ed.** from the x
17c40 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
17c50 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
17c60 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
17c70 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c bject..** ^On al
17c80 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 l subsequent inv
17c90 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 ocations, the ps
17ca0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
17cb0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
17cc0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
17cd0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
17ce0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
17cf0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
17d00 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 .** method..*/.v
17d10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 oid sqlite3_rand
17d20 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
17d30 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
17d40 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
17d50 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
17d60 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
17d70 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
17d80 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 e registers a au
17d90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
17da0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
17db0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
17dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
17dd0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
17de0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
17df0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
17e00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
17e10 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
17e20 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
17e30 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
17e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
17e50 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
17e60 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
17e70 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
17e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
17e90 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
17ea0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
17eb0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
17ec0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
17ed0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
17ee0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
17ef0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
17f00 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
17f10 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
17f20 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
17f30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
17f40 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
17f50 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
17f60 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
17f70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
17f80 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
17f90 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
17fa0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
17fb0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
17fc0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
17fd0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
17fe0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
17ff0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
18000 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
18010 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
18020 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
18030 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
18040 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
18050 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
18060 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
18070 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
18080 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
18090 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
180a0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
180b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
180c0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
180d0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
180e0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
180f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
18100 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
18110 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
18120 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
18130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
18140 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
18150 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
18160 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
18170 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
18180 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
18190 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
181a0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
181b0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
181c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
181d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
181e0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
181f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
18200 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
18210 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
18220 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
18230 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
18240 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
18250 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
18260 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
18270 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
18280 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
18290 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
182a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
182b0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
182c0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
182d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
182e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
182f0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
18300 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
18310 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
18320 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
18330 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
18340 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
18350 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
18360 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
18370 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
18380 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
18390 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
183a0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
183b0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
183c0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
183d0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
183e0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
183f0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
18400 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
18410 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
18420 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
18430 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
18440 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
18450 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
18460 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
18470 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
18480 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
18490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
184a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
184b0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
184c0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
184d0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
184e0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
184f0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
18500 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
18510 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
18520 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
18530 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
18540 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
18550 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
18560 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
18570 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
18580 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
18590 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
185a0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
185b0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
185c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
185d0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
185e0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
185f0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
18600 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
18610 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
18620 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
18630 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
18640 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
18650 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
18660 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
18670 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
18680 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
18690 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
186a0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
186b0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
186c0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
186d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
186e0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
186f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
18700 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
18710 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
18720 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
18730 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
18740 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
18750 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
18760 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
18770 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
18780 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
18790 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
187a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
187b0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
187c0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
187d0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
187e0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
187f0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
18800 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
18810 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
18820 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
18830 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
18840 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
18850 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
18860 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
18870 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
18880 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
18890 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
188a0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
188b0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
188c0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
188d0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
188e0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
188f0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
18900 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
18910 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
18920 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
18930 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
18940 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
18950 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
18960 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
18970 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
18980 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
18990 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
189a0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
189b0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
189c0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
189d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
189e0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
189f0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
18a00 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
18a10 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
18a20 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
18a30 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
18a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
18a50 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
18a60 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
18a70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
18a80 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
18a90 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
18aa0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
18ab0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
18ac0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
18ad0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
18ae0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
18af0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
18b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
18b10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
18b20 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
18b30 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
18b40 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
18b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
18b60 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
18b70 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
18b80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
18b90 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
18ba0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
18bb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
18bc0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
18bd0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
18be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
18bf0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
18c00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
18c10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
18c20 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
18c30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
18c40 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
18c50 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
18c60 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
18c70 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
18c80 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
18c90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
18ca0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
18cb0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
18cc0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
18cd0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
18ce0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
18cf0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
18d00 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
18d10 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
18d20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
18d30 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
18d40 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
18d50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
18d60 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
18d70 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
18d80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
18d90 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
18da0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
18db0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
18dc0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
18dd0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
18de0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
18df0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
18e00 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
18e10 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
18e20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
18e30 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
18e40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
18e50 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
18e60 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
18e70 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
18e80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
18e90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
18ea0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
18eb0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
18ec0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
18ed0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
18ee0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
18ef0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
18f00 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
18f10 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
18f20 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
18f30 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
18f40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
18f50 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
18f60 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
18f70 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
18f80 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
18f90 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
18fa0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
18fb0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
18fc0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
18fd0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
18fe0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
18ff0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
19000 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
19010 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
19020 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
19030 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
19040 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
19050 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 ormation..*/.#de
19060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
19070 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
19080 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
19090 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
190a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
190b0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
190c0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
190d0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
190e0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
190f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
19100 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
19110 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
19120 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
19130 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
19140 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
19150 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
19160 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
19170 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
19180 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
19190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
191a0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
191b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
191c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
191d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
191e0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
191f0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
19200 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
19210 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
19220 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
19230 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
19240 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
19250 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
19260 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
19270 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
19280 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
19290 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
192a0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
192b0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
192c0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
192d0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
192e0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
192f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
19300 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
19310 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
19320 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
19330 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
19340 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
19350 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
19360 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 meter. ^(The 5t
19370 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
19380 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
19390 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
193a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
193b0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
193c0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 temp",.** etc.)
193d0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e if applicable.)^
193e0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d ^The 6th param
193f0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
19400 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
19410 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
19420 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
19430 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
19440 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
19450 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
19460 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
19470 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
19480 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
19490 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
194a0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
194b0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
194c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
194d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
194e0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
194f0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
19500 2a 2a 2a 2a 2a 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 49 4e SQLITE_CREATE_IN
19520 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
19530 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
19540 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
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 41 42 QLITE_CREATE_TAB
19570 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
19580 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
19590 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
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 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
195d0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
195e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
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 45 4d 50 5f ITE_CREATE_TEMP_
19610 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
19620 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
19630 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
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 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
19660 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
19670 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
19680 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
19690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
196a0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
196b0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
196c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew 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 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
19700 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
19710 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger 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 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
19750 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
19760 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w 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 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
197a0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
197b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
197c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
197d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
197e0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
197f0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
19800 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
19810 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#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 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
19840 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
19850 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
19860 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#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 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
19890 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
198a0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
198b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
198c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
198d0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
198e0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
198f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
19900 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
19910 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
19920 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
19930 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
19940 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
19950 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
19960 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
19970 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
19980 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View 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 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
199c0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
199d0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
199e0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
199f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
19a00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
19a10 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
19a20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
19a30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
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 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
19a60 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
19a70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
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 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
19ab0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
19ac0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
19ad0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
19ae0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
19af0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
19b00 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
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 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
19b50 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
19b60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
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 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
19ba0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
19bb0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration 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 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
19bf0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
19c00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
19c10 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19c30 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
19c40 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
19c50 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename 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 44 #define SQLITE_D
19c80 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
19c90 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
19ca0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base 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 41 4c define SQLITE_AL
19cd0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
19ce0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
19cf0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
19d00 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
19d20 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
19d30 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
19d40 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
19d50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
19d70 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
19d80 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
19d90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
19da0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
19db0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
19dc0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
19dd0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
19de0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
19df0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
19e00 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
19e10 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
19e20 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
19e30 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
19e40 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
19e50 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
19e60 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
19e70 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
19e80 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
19e90 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
19ea0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
19eb0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
19ec0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
19ed0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
19ee0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
19ef0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
19f00 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
19f10 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
19f20 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
19f30 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
19f40 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
19f50 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
19f60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
19f70 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
19f80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
19f90 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
19fa0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
19fb0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
19fc0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
19fd0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
19fe0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
19ff0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1a000 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
1a010 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
1a020 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
1a030 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
1a040 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
1a050 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
1a060 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
1a070 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
1a080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1a090 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
1a0a0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
1a0b0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
1a0c0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
1a0d0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
1a0e0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
1a0f0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
1a100 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
1a110 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
1a120 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
1a130 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
1a140 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
1a150 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
1a160 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
1a170 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
1a180 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
1a190 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
1a1a0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
1a1b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
1a1c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
1a1d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
1a1e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
1a1f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
1a200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
1a210 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
1a220 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1a230 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
1a240 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1a250 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
1a260 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
1a270 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
1a280 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
1a290 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
1a2a0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
1a2b0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
1a2c0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
1a2d0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
1a2e0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
1a2f0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
1a300 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
1a310 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
1a320 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
1a330 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
1a340 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
1a350 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
1a360 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
1a370 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
1a380 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
1a390 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
1a3a0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
1a3b0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
1a3c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
1a3d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
1a3e0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
1a3f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
1a400 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
1a410 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
1a420 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
1a430 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1a440 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 Lite..*/.void *s
1a450 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
1a460 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
1a470 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
1a480 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
1a490 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
1a4a0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
1a4b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
1a4c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
1a4d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
1a4e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
1a4f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
1a500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1a510 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
1a520 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ss Callbacks.**.
1a530 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1a540 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
1a550 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
1a560 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
1a570 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
1a580 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
1a590 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
1a5a0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
1a5b0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
1a5c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1a5d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
1a5e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
1a5f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
1a600 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
1a610 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
1a620 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
1a630 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
1a640 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
1a650 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
1a660 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
1a670 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
1a680 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
1a690 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
1a6a0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
1a6b0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
1a6c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
1a6d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
1a6e0 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 N is the number
1a6f0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
1a700 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
1a710 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
1a720 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
1a730 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
1a740 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
1a750 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a e callback X..**
1a760 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 .** ^Only a sing
1a770 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 le progress hand
1a780 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e ler may be defin
1a790 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 ed at one time p
1a7a0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 er.** [database
1a7b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 connection]; set
1a7c0 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 ting a new progr
1a7d0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 ess handler canc
1a7e0 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f els the.** old o
1a7f0 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 ne. ^Setting pa
1a800 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c rameter X to NUL
1a810 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 L disables the p
1a820 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
1a830 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 .** ^The progres
1a840 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 s handler is als
1a850 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 o disabled by se
1a860 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c tting N to a val
1a870 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 ue less.** than
1a880 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 1..**.** ^If the
1a890 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
1a8a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
1a8b0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 ero, the operati
1a8c0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
1a8d0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
1a8e0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
1a8f0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
1a900 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
1a910 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 n on a GUI progr
1a920 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a ess dialog box..
1a930 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 **.** The progre
1a940 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 ss handler callb
1a950 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
1a960 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1a970 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1a980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1a990 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1a9a0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
1a9b0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
1a9c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
1a9d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1a9e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1a9f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
1aa00 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
1aa10 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
1aa20 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
1aa30 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
1aa40 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a aragraph..**.*/.
1aa50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f void sqlite3_pro
1aa60 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
1aa70 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
1aa80 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
1aa90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1aaa0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
1aab0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
1aac0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ection.**.** ^Th
1aad0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
1aae0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
1aaf0 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 base file whose
1ab00 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 name is given by
1ab10 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
1ab20 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 argument. ^The
1ab30 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1ab40 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
1ab50 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
1ab60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1ab70 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
1ab80 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
1ab90 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
1aba0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
1abb0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
1abc0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 16(). ^(A [datab
1abd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1abe0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
1abf0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
1ac00 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
1ac10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
1ac20 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
1ac30 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
1ac40 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
1ac50 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
1ac60 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
1ac70 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
1ac80 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
1ac90 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
1aca0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
1acb0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
1acc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
1acd0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 ** object.)^ ^(I
1ace0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
1acf0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 s opened (and/or
1ad00 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 created) succes
1ad10 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 sfully, then.**
1ad20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1ad30 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
1ad40 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
1ad50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
1ad60 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 )^ ^The.** [sqli
1ad70 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
1ad80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1ad90 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
1ada0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
1adb0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
1adc0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
1add0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
1ade0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 rror following a
1adf0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a failure of any.
1ae00 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
1ae10 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 3_open() routine
1ae20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 s..**.** ^The de
1ae30 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 fault encoding f
1ae40 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
1ae50 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 will be UTF-8 if
1ae60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
1ae70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
1ae80 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 en_v2() is calle
1ae90 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 d and.** UTF-16
1aea0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1aeb0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 te order if sqli
1aec0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 te3_open16() is
1aed0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 used..**.** Whet
1aee0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 her or not an er
1aef0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 ror occurs when
1af00 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 it is opened, re
1af10 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 sources.** assoc
1af20 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
1af30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1af40 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 ion] handle shou
1af50 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 ld be released b
1af60 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 y.** passing it
1af70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
1af80 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 e()] when it is
1af90 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 no longer requir
1afa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
1afb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1afc0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 interface works
1afd0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 like sqlite3_ope
1afe0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
1aff0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 at it accepts tw
1b000 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 o additional par
1b010 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 ameters for addi
1b020 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a tional control.*
1b030 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 * over the new d
1b040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b050 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 on. ^(The flags
1b060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
1b070 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1b080 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 () can take one
1b090 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
1b0a0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
1b0b0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
1b0c0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
1b0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1b0e0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 NOMUTEX], [SQLIT
1b0f0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
1b100 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
1b110 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a SHAREDCACHE],.**
1b120 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
1b130 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
1b140 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a E] flags:)^.**.*
1b150 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
1b160 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
1b170 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c DONLY]</dt>.** <
1b180 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1b190 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 is opened in rea
1b1a0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 d-only mode. If
1b1b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
1b1c0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 es not.** alread
1b1d0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
1b1e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
1b1f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1b200 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
1b210 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a EADWRITE]</dt>.*
1b220 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1b230 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
1b240 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
1b250 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
1b260 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 , or reading.**
1b270 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 only if the file
1b280 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 is write protec
1b290 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 ted by the opera
1b2a0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e ting system. In
1b2b0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 either.** case
1b2c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 the database mus
1b2d0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c t already exist,
1b2e0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
1b2f0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
1b300 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
1b310 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
1b320 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
1b330 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1b340 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
1b350 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1b360 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
1b370 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
1b380 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 nd is creates it
1b390 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
1b3a0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
1b3b0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
1b3c0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
1b3d0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
1b3e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1b3f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1b400 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a n16().</dd>)^.**
1b410 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
1b420 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
1b430 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
1b440 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
1b450 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
1b460 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
1b470 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 bove or one of t
1b480 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 he combinations
1b490 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 shown above comb
1b4a0 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ined.** with the
1b4b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
1b4c0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
1b4d0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c OPEN_FULLMUTEX],
1b4e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1b4f0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e _SHAREDCACHE] an
1b500 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 d/or [SQLITE_OPE
1b510 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
1b520 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 flags,.** then t
1b530 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
1b540 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
1b550 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
1b560 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
1b570 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
1b580 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1b590 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
1b5a0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
1b5b0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
1b5c0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
1b5d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
1b5e0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
1b5f0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
1b600 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
1b610 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
1b620 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
1b630 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
1b640 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
1b650 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1b660 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
1b670 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
1b680 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
1b690 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
1b6a0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
1b6b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
1b6c0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
1b6d0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
1b6e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
1b6f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
1b700 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
1b710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1b720 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
1b730 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
1b740 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
1b750 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
1b760 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
1b770 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
1b780 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
1b790 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
1b7a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
1b7b0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
1b7c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
1b7d0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
1b7e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
1b7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
1b800 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
1b810 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
1b820 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
1b830 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
1b840 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1b850 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
1b860 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
1b870 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
1b880 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
1b890 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
1b8a0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
1b8b0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e ction. ^This in
1b8c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
1b8d0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
1b8e0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
1b8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1b900 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
1b910 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1b920 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
1b930 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
1b940 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
1b950 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
1b960 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
1b970 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
1b980 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
1b990 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
1b9a0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
1b9b0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
1b9c0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
1b9d0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
1b9e0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
1b9f0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
1ba00 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
1ba10 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
1ba20 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
1ba30 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
1ba40 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 is an empty str
1ba50 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
1ba60 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a ate, temporary.*
1ba70 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 * on-disk databa
1ba80 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
1ba90 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 ed. ^This priva
1baa0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c te database will
1bab0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 be.** automatic
1bac0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 ally deleted as
1bad0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 soon as the data
1bae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1baf0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
1bb00 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
1bb10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1bb20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
1bb30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
1bb40 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
1bb50 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
1bb60 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
1bb70 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
1bb80 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
1bb90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1bba0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
1bbb0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 e. ^If the four
1bbc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
1bbd0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
1bbe0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
1bbf0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
1bc00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
1bc10 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
1bc20 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
1bc30 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
1bc40 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
1bc50 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1bc60 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
1bc70 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1bc80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
1bc90 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
1bca0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
1bcb0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
1bcc0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
1bcd0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
1bce0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
1bcf0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
1bd00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
1bd10 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
1bd20 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
1bd30 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
1bd40 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
1bd50 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e open_v2()..*/.in
1bd60 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
1bd70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
1bd80 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
1bd90 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
1bda0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
1bdb0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
1bdc0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
1bdd0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
1bde0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
1bdf0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
1be00 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
1be10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
1be20 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
1be30 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1be40 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
1be50 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1be60 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
1be70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
1be80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
1be90 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
1bea0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
1beb0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
1bec0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
1bed0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
1bee0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
1bef0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
1bf00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
1bf10 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
1bf20 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
1bf30 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
1bf40 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
1bf50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1bf60 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
1bf70 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
1bf80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1bf90 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
1bfa0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
1bfb0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
1bfc0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
1bfd0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1bfe0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
1bff0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
1c000 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
1c010 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
1c020 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
1c030 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
1c040 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
1c050 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
1c060 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
1c070 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
1c080 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
1c090 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
1c0a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
1c0b0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
1c0c0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
1c0d0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
1c0e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
1c0f0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
1c100 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
1c110 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
1c120 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1c130 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
1c140 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1c150 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
1c160 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
1c170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
1c180 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
1c190 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
1c1a0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
1c1b0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
1c1c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
1c1d0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
1c1e0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
1c1f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
1c200 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
1c210 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
1c220 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
1c230 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
1c240 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
1c250 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
1c260 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
1c270 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
1c280 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
1c290 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
1c2a0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
1c2b0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
1c2c0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
1c2d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
1c2e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
1c2f0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
1c300 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
1c310 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
1c320 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
1c330 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
1c340 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
1c350 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
1c360 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
1c370 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
1c380 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
1c390 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
1c3a0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
1c3b0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
1c3c0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
1c3d0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
1c3e0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
1c3f0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
1c400 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
1c410 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
1c420 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
1c430 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
1c440 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
1c450 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
1c460 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
1c470 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
1c480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c490 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
1c4a0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
1c4b0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
1c4c0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
1c4d0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
1c4e0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
1c4f0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
1c500 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
1c510 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
1c520 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
1c530 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
1c540 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
1c550 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
1c560 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
1c570 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
1c580 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
1c590 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
1c5a0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
1c5b0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
1c5c0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
1c5d0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
1c5e0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
1c5f0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
1c600 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
1c610 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
1c620 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 be set..*/.int s
1c630 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 qlite3_errcode(s
1c640 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 qlite3 *db);.int
1c650 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
1c660 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
1c670 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 3 *db);.const ch
1c680 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d ar *sqlite3_errm
1c690 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f sg(sqlite3*);.co
1c6a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1c6b0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 3_errmsg16(sqlit
1c6c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
1c6d0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 I3REF: SQL State
1c6e0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b ment Object.** K
1c6f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
1c700 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
1c710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1c720 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
1c730 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
1c740 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
1c750 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
1c760 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 tement..** This
1c770 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 object is variou
1c780 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 sly known as a "
1c790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c7a0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d nt" or a.** "com
1c7b0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
1c7c0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 ent" or simply a
1c7d0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e s a "statement".
1c7e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 .**.** The life
1c7f0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f of a statement o
1c800 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 bject goes somet
1c810 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a hing like this:.
1c820 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
1c830 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 i> Create the ob
1c840 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
1c850 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1c860 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a ] or a related.*
1c870 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e * function.
1c880 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
1c890 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 lues to [host pa
1c8a0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 rameters] using
1c8b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1c8c0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 _*().** int
1c8d0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e erfaces..** <li>
1c8e0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 Run the SQL by
1c8f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1c900 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 _step()] one or
1c910 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
1c920 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 li> Reset the st
1c930 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
1c940 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1c950 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
1c960 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
1c970 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
1c980 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
1c990 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
1c9a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1c9b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1c9c0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a )]..** </ol>.**.
1c9d0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 ** Refer to docu
1c9e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 mentation on ind
1c9f0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 ividual methods
1ca00 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 above for additi
1ca10 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
1ca20 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
1ca30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
1ca40 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
1ca50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1ca60 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
1ca70 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 ts.**.** ^(This
1ca80 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
1ca90 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
1caa0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
1cab0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
1cac0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
1cad0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
1cae0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
1caf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1cb00 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
1cb10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
1cb20 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
1cb30 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
1cb40 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
1cb50 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
1cb60 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
1cb70 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
1cb80 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
1cb90 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
1cba0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
1cbb0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
1cbc0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
1cbd0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
1cbe0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
1cbf0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
1cc00 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
1cc10 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
1cc20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
1cc30 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
1cc40 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
1cc50 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
1cc60 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
1cc70 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
1cc80 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
1cc90 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
1cca0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
1ccb0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
1ccc0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
1ccd0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
1cce0 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
1ccf0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
1cd00 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
1cd10 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
1cd20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
1cd30 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
1cd40 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
1cd50 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
1cd60 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
1cd70 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
1cd80 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
1cd90 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
1cda0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
1cdb0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
1cdc0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
1cdd0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
1cde0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
1cdf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
1ce00 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
1ce10 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
1ce20 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
1ce30 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
1ce40 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
1ce50 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
1ce60 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
1ce70 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
1ce80 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
1ce90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
1cea0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
1ceb0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
1cec0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
1ced0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
1cee0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
1cef0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
1cf00 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
1cf10 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
1cf20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
1cf30 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
1cf40 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
1cf50 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
1cf60 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
1cf70 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
1cf80 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
1cf90 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
1cfa0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
1cfb0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
1cfc0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
1cfd0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
1cfe0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
1cff0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
1d000 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
1d010 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
1d020 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
1d030 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
1d040 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
1d050 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
1d060 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
1d070 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
1d080 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
1d090 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
1d0a0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
1d0b0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
1d0c0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
1d0d0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
1d0e0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
1d0f0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
1d100 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
1d110 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1d120 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
1d130 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
1d140 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
1d150 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
1d160 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
1d170 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
1d180 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
1d190 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
1d1a0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
1d1b0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
1d1c0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
1d1d0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
1d1e0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
1d1f0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
1d200 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
1d210 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
1d220 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
1d230 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
1d240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d250 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
1d260 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
1d270 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
1d280 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
1d290 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
1d2a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
1d2b0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
1d2c0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
1d2d0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
1d2e0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
1d2f0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
1d300 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
1d310 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
1d320 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
1d330 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
1d340 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
1d350 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
1d360 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
1d370 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
1d380 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
1d390 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
1d3a0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
1d3b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1d3c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
1d3d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 dd>The maximum s
1d3e0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e ize of any strin
1d3f0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 g or BLOB or tab
1d400 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 le row, in bytes
1d410 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 .<dd>)^.**.** ^(
1d420 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1d430 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e _SQL_LENGTH</dt>
1d440 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1d450 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e mum length of an
1d460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1d470 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e in bytes.</dd>)^
1d480 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1d490 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
1d4a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1d4b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1d4c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
1d4d0 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e table definition
1d4e0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 or in the.** re
1d4f0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
1d500 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 ELECT] or the ma
1d510 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1d520 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e columns in an in
1d530 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 dex.** or in an
1d540 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
1d550 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 P BY clause.</dd
1d560 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
1d570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
1d580 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
1d590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1d5a0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 depth of the par
1d5b0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 se tree on any e
1d5c0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 xpression.</dd>)
1d5d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
1d5e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
1d5f0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
1d600 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d610 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
1d620 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
1d630 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
1d640 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 t.</dd>)^.**.**
1d650 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1d660 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a IT_VDBE_OP</dt>.
1d670 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d680 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 um number of ins
1d690 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 tructions in a v
1d6a0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 irtual machine p
1d6b0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 rogram.** used t
1d6c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 o implement an S
1d6d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 QL statement. T
1d6e0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 his limit is not
1d6f0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e currently.** en
1d700 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 forced, though t
1d710 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 hat might be add
1d720 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 ed in some futur
1d730 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 e release of.**
1d740 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a SQLite.</dd>)^.*
1d750 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 *.** ^(<dt>SQLIT
1d760 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
1d770 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _ARG</dt>.** <dd
1d780 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
1d790 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
1d7a0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c on a function.<
1d7b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
1d7c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1d7d0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
1d7e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1d7f0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
1d800 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
1d810 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
1d820 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1d830 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
1d840 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 ATTERN_LENGTH</d
1d850 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1d860 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1d870 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 the pattern argu
1d880 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b ment to the [LIK
1d890 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 E] or.** [GLOB]
1d8a0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 operators.</dd>)
1d8b0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ^.**.** ^(<dt>SQ
1d8c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
1d8d0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
1d8e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d8f0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
1d900 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
1d910 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
1d920 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
1d930 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
1d940 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
1d950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1d960 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
1d970 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 f recursion for
1d980 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e triggers.</dd>)^
1d990 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
1d9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1d9b0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 T_LENGTH
1d9c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 0.#d
1d9d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1d9e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 IT_SQL_LENGTH
1d9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
1da00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1da10 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 MIT_COLUMN
1da20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
1da30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1da40 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 IMIT_EXPR_DEPTH
1da50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
1da60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1da70 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
1da80 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
1da90 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
1daa0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 _LIMIT_VDBE_OP
1dab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1dac0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
1dad0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
1dae0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 _ARG
1daf0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
1db00 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
1db10 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
1db20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
1db30 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
1db40 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 ATTERN_LENGTH
1db50 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
1db60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
1db70 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 BLE_NUMBER
1db80 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
1db90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
1dba0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 GER_DEPTH
1dbb0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 10../*.** C
1dbc0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 API3REF: Compili
1dbd0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d ng An SQL Statem
1dbe0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ent.** KEYWORDS:
1dbf0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 {SQL statement
1dc00 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 compiler}.**.**
1dc10 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
1dc20 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
1dc30 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
1dc40 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
1dc50 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
1dc60 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
1dc70 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
1dc80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
1dc90 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 ment, "db", is a
1dca0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1dcb0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 ction] obtained
1dcc0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 from a.** prior
1dcd0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
1dce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1dcf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1dd00 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b en_v2()] or.** [
1dd10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1dd20 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 ]. The database
1dd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
1dd40 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 not have been c
1dd50 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
1dd60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1dd70 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 , "zSql", is the
1dd80 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
1dd90 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
1dda0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
1ddb0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
1ddc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
1ddd0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
1dde0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1ddf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
1de00 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 se UTF-8, and sq
1de10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1de20 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
1de30 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
1de40 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a use UTF-16..**.*
1de50 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 * ^If the nByte
1de60 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 argument is less
1de70 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e than zero, then
1de80 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
1de90 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
1dea0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
1deb0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e . ^If nByte is n
1dec0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1ded0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 n it is the maxi
1dee0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 mum.** number of
1def0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f bytes read fro
1df00 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e m zSql. ^When n
1df10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
1df20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 tive, the.** zSq
1df30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 l string ends at
1df40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 either the firs
1df50 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 t '\000' or '\u0
1df60 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 000' character o
1df70 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 r.** the nByte-t
1df80 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 h byte, whicheve
1df90 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 r comes first. I
1dfa0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
1dfb0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 ws.** that the s
1dfc0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 upplied string i
1dfd0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 s nul-terminated
1dfe0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 , then there is
1dff0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f a small.** perfo
1e000 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 rmance advantage
1e010 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 to be gained by
1e020 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
1e030 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
1e040 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 .** is equal to
1e050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
1e060 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
1e070 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
1e080 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
1e090 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 nul-terminator b
1e0a0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ytes..**.** ^If
1e0b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
1e0c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
1e0d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
1e0e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
1e0f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
1e100 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
1e110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1e120 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
1e130 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
1e140 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
1e150 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
1e160 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
1e170 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
1e180 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
1e190 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
1e1a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
1e1b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
1e1c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
1e1d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1e1e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
1e1f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
1e200 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e210 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
1e220 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
1e230 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
1e240 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
1e250 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
1e260 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
1e270 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
1e280 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
1e290 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
1e2a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
1e2b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
1e2c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
1e2d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1e2e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
1e2f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
1e300 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1e310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1e320 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
1e330 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1e340 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
1e350 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
1e360 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
1e370 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
1e380 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
1e390 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
1e3a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
1e3b0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
1e3c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
1e3d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1e3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
1e3f0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
1e400 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1e410 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
1e420 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
1e430 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
1e440 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
1e450 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
1e460 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
1e470 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1e480 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
1e490 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
1e4a0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e iscouraged..** ^
1e4b0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
1e4c0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 rfaces, the prep
1e4d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
1e4e0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e * that is return
1e4f0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
1e500 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 _stmt] object) c
1e510 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f ontains a copy o
1e520 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 f the.** origina
1e530 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 l SQL text. This
1e540 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c causes the [sql
1e550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 ite3_step()] int
1e560 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 erface to.** beh
1e570 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ave differently
1e580 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a in three ways:.*
1e590 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
1e5a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 >.** ^If the dat
1e5b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
1e5c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 nges, instead of
1e5d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
1e5e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 TE_SCHEMA] as it
1e5f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 .** always used
1e600 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f to do, [sqlite3_
1e610 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 step()] will aut
1e620 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
1e630 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 pile the SQL.**
1e640 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 statement and tr
1e650 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 y to run it agai
1e660 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a n..** </li>.**.*
1e670 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 * <li>.** ^When
1e680 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
1e690 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1e6a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e ] will return on
1e6b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 e of the detaile
1e6c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 d.** [error code
1e6d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 s] or [extended
1e6e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e error codes]. ^
1e6f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
1e700 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
1e710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e720 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
1e730 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
1e740 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
1e750 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 lt code.** and t
1e760 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 he application w
1e770 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
1e780 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
1e790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
1e7a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 t()].** in order
1e7b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
1e7c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
1e7d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 the problem. Wi
1e7e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 th the "v2" prep
1e7f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 are.** interface
1e800 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
1e810 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
1e820 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
1e830 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ed immediately..
1e840 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
1e850 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 li>.** ^If the s
1e860 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f pecific value bo
1e870 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 und to [paramete
1e880 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 r | host paramet
1e890 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 er] in the .** W
1e8a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 HERE clause migh
1e8b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
1e8c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
1e8d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 plan for a state
1e8e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ment,.** then th
1e8f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c e statement will
1e900 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
1e910 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 y recompiled, as
1e920 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 if there had be
1e930 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 en .** a schema
1e940 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 change, on the f
1e950 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 irst [sqlite3_s
1e960 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c tep()] call foll
1e970 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 owing any change
1e980 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
1e990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
1e9a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 bindings] of tha
1e9b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a t [parameter]. .
1e9c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 ** ^The specific
1e9d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d value of WHERE-
1e9e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 clause [paramete
1e9f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e r] might influen
1ea00 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 ce the .** choic
1ea10 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
1ea20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1ea30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e is the left-han
1ea40 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b d side of a [LIK
1ea50 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 E].** or [GLOB]
1ea60 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 operator or if t
1ea70 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
1ea80 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 compared to an i
1ea90 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a ndexed column.**
1eaa0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 and the [SQLITE
1eab0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 _ENABLE_STAT2] c
1eac0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
1ead0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
1eae0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a * the .** </li>.
1eaf0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 ** </ol>.*/.int
1eb00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1eb10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1eb20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1eb30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1eb40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1eb50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1eb60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1eb70 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
1eb80 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1eb90 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1eba0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1ebb0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1ebc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1ebd0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1ebe0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1ebf0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1ec00 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
1ec10 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1ec20 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1ec30 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
1ec40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1ec50 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 re_v2(. sqlite3
1ec60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1ec70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
1ec80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1ec90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
1eca0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
1ecb0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
1ecc0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1ecd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1ece0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1ecf0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1ed00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1ed10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1ed20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1ed30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1ed40 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
1ed50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1ed60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1ed70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1ed80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
1ed90 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
1eda0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1edb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1edc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1edd0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
1ede0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1edf0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
1ee00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1ee10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1ee20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1ee30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1ee40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1ee50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1ee60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1ee70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1ee80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
1ee90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1eea0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1eeb0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1eec0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
1eed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1eee0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
1eef0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
1ef00 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
1ef10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1ef20 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
1ef30 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
1ef40 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1ef50 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1ef70 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1ef80 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1ef90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1efa0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1efb0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1efc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1efd0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
1efe0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1eff0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1f000 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1f010 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1f020 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 REF: Retrieving
1f030 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a Statement SQL.**
1f040 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 .** ^This interf
1f050 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
1f060 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
1f070 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
1f080 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
1f090 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
1f0a0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
1f0b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
1f0c0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
1f0d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
1f0e0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
1f0f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1f110 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f pare16_v2()]..*/
1f120 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1f130 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
1f140 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
1f150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f160 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
1f170 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 SQL Statement Wr
1f180 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 ites The Databas
1f190 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
1f1a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
1f1b0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 ly(X) interface
1f1c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f returns true (no
1f1d0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 74 68 n-zero) if.** th
1f1e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1f1f0 65 6d 65 6e 74 5d 20 58 20 69 73 20 5b 53 45 4c ement] X is [SEL
1f200 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ECT] statement a
1f210 6e 64 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 20 nd false (zero)
1f220 69 66 0a 2a 2a 20 58 20 69 73 20 61 6e 20 5b 49 if.** X is an [I
1f230 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
1f240 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 43 52 45 41 , [DELETE], CREA
1f250 54 45 2c 20 44 52 4f 50 2c 20 5b 41 4e 41 4c 59 TE, DROP, [ANALY
1f260 5a 45 5d 2c 0a 2a 2a 20 5b 41 4c 54 45 52 5d 2c ZE],.** [ALTER],
1f270 20 6f 72 20 5b 52 45 49 4e 44 45 58 5d 20 73 74 or [REINDEX] st
1f280 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 49 66 20 58 atement..** If X
1f290 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1f2a0 65 72 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 er or any other
1f2b0 6b 69 6e 64 20 6f 66 20 73 74 61 74 65 6d 65 6e kind of statemen
1f2c0 74 2c 20 69 6e 63 6c 75 64 69 6e 67 20 62 75 74 t, including but
1f2d0 0a 2a 2a 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 .** not limited
1f2e0 74 6f 20 5b 41 54 54 41 43 48 5d 2c 20 5b 44 45 to [ATTACH], [DE
1f2f0 54 41 43 48 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c TACH], [COMMIT],
1f300 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 20 5b 52 45 [ROLLBACK], [RE
1f310 4c 45 41 53 45 5d 2c 0a 2a 2a 20 5b 53 41 56 45 LEASE],.** [SAVE
1f320 50 4f 49 4e 54 5d 2c 20 5b 50 52 41 47 4d 41 5d POINT], [PRAGMA]
1f330 2c 20 6f 72 20 5b 56 41 43 55 55 4d 5d 20 74 68 , or [VACUUM] th
1f340 65 20 72 65 73 75 6c 74 20 6f 66 20 73 71 6c 69 e result of sqli
1f350 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
1f360 79 28 58 29 20 69 73 0a 2a 2a 20 75 6e 64 65 66 y(X) is.** undef
1f370 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ined..*/.int sql
1f380 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
1f390 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ly(sqlite3_stmt
1f3a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
1f3b0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 CAPI3REF: Dynami
1f3c0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 cally Typed Valu
1f3d0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 e Object.** KEYW
1f3e0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 ORDS: {protected
1f3f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 sqlite3_value}
1f400 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c {unprotected sql
1f410 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a ite3_value}.**.*
1f420 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 * SQLite uses th
1f430 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
1f440 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 object to repres
1f450 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a ent all values.*
1f460 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 * that can be st
1f470 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 ored in a databa
1f480 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 se table. SQLite
1f490 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 uses dynamic ty
1f4a0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ping.** for the
1f4b0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 values it stores
1f4c0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 . ^Values store
1f4d0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c d in sqlite3_val
1f4e0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 ue objects.** ca
1f4f0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 n be integers, f
1f500 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
1f510 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 lues, strings, B
1f520 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a LOBs, or NULL..*
1f530 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f *.** An sqlite3_
1f540 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
1f550 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 be either "prot
1f560 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f ected" or "unpro
1f570 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 tected"..** Some
1f580 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
1f590 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 ire a protected
1f5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 sqlite3_value.
1f5b0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 Other interfaces
1f5c0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 .** will accept
1f5d0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 either a protect
1f5e0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 ed or an unprote
1f5f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1f600 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 ue..** Every int
1f610 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 erface that acce
1f620 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 pts sqlite3_valu
1f630 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 e arguments spec
1f640 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 ifies.** whether
1f650 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 or not it requi
1f660 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 res a protected
1f670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
1f680 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 *.** The terms "
1f690 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 protected" and "
1f6a0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 unprotected" ref
1f6b0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 er to whether or
1f6c0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 not.** a mutex
1f6d0 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 is held. A inte
1f6e0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 rnal mutex is he
1f6f0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 ld for a protect
1f700 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1f710 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e lue object but n
1f720 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 o mutex is held
1f730 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 for an unprotect
1f740 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1f750 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 lue object. If
1f760 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
1f770 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d ed to be single-
1f780 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 threaded.** (wit
1f790 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 h [SQLITE_THREAD
1f7a0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 SAFE=0] and with
1f7b0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
1f7c0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e safe()] returnin
1f7d0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 g 0).** or if SQ
1f7e0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f Lite is run in o
1f7f0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 ne of reduced mu
1f800 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 tex modes .** [S
1f810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
1f820 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 GLETHREAD] or [S
1f830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1f840 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 TITHREAD].** the
1f850 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 n there is no di
1f860 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
1f870 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
1f880 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
1f890 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1f8a0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 ects and they ca
1f8b0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 n be used interc
1f8c0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 hangeably. Howe
1f8d0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 ver,.** for maxi
1f8e0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 mum code portabi
1f8f0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d lity it is recom
1f900 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
1f910 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c ications.** stil
1f920 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 l make the disti
1f930 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
1f940 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
1f950 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1f960 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1f970 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 s even when not
1f980 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 strictly require
1f990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
1f9a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1f9b0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
1f9c0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
1f9d0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
1f9e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1f9f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
1fa00 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
1fa10 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
1fa20 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
1fa30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1fa40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
1fa50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
1fa60 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f alue()] is unpro
1fa70 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f tected..** Unpro
1fa80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1fa90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 alue objects may
1faa0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 only be used wi
1fab0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 th.** [sqlite3_r
1fac0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 esult_value()] a
1fad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
1fae0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 _value()]..** Th
1faf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
1fb00 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
1fb10 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 value_type()] fa
1fb20 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 mily of.** inter
1fb30 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 faces require pr
1fb40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1fb50 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a value objects..*
1fb60 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
1fb70 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c Mem sqlite3_val
1fb80 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ue;../*.** CAPI3
1fb90 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f REF: SQL Functio
1fba0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 n Context Object
1fbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 .**.** The conte
1fbc0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 xt in which an S
1fbd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 QL function exec
1fbe0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 utes is stored i
1fbf0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n an.** sqlite3_
1fc00 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 context object.
1fc10 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 ^A pointer to a
1fc20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
1fc30 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
1fc40 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
1fc50 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
1fc60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
1fc70 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
1fc80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
1fc90 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1fca0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
1fcb0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
1fcc0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
1fcd0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
1fce0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
1fcf0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
1fd00 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
1fd10 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
1fd20 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
1fd30 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
1fd40 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
1fd50 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
1fd60 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
1fd70 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
1fd80 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
1fd90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
1fda0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
1fdb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
1fdc0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
1fdd0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
1fde0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
1fdf0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
1fe00 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a red Statements.*
1fe10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 * KEYWORDS: {hos
1fe20 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f t parameter} {ho
1fe30 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b st parameters} {
1fe40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
1fe50 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ame}.** KEYWORDS
1fe60 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 : {SQL parameter
1fe70 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 } {SQL parameter
1fe80 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 s} {parameter bi
1fe90 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 nding}.**.** ^(I
1fea0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
1feb0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 ent text input t
1fec0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
1fed0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 re_v2()] and its
1fee0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 variants,.** li
1fef0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 terals may be re
1ff00 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 placed by a [par
1ff10 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 ameter] that mat
1ff20 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c ches one of foll
1ff30 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 owing.** templat
1ff40 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
1ff50 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 * <li> ?.** <li
1ff60 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 > ?NNN.** <li>
1ff70 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 :VVV.** <li> @
1ff80 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 VVV.** <li> $VV
1ff90 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a V.** </ul>.**.**
1ffa0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 In the template
1ffb0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 s above, NNN rep
1ffc0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 resents an integ
1ffd0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 er literal,.** a
1ffe0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 nd VVV represent
1fff0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 s an alphanumeri
20000 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 c identifier.)^
20010 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 ^The values of
20020 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 these.** paramet
20030 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 ers (also called
20040 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 "host parameter
20050 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 names" or "SQL
20060 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 parameters").**
20070 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 can be set using
20080 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
20090 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 d_*() routines d
200a0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a efined here..**.
200b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
200c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
200d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
200e0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 outines is alway
200f0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
20100 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 o the [sqlite3_s
20110 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 tmt] object retu
20120 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 rned from.** [sq
20130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20140 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
20150 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
20160 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
20170 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
20180 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 the SQL paramete
20190 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 r to be set..**
201a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 ^The leftmost SQ
201b0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 L parameter has
201c0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 an index of 1.
201d0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e ^When the same n
201e0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 amed.** SQL para
201f0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f meter is used mo
20200 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 re than once, se
20210 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
20220 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 ent.** occurrenc
20230 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 es have the same
20240 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 index as the fi
20250 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a rst occurrence..
20260 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f ** ^The index fo
20270 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 r named paramete
20280 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 rs can be looked
20290 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a up using the.**
202a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
202b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
202c0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 ] API if desired
202d0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a . ^The index.**
202e0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 for "?NNN" para
202f0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 meters is the va
20300 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e lue of NNN..** ^
20310 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 The NNN value mu
20320 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 st be between 1
20330 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 and the [sqlite3
20340 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 _limit()].** par
20350 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c ameter [SQLITE_L
20360 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
20370 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 MBER] (default v
20380 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a alue: 999)..**.*
20390 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 * ^The third arg
203a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c ument is the val
203b0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 ue to bind to th
203c0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a e parameter..**.
203d0 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f ** ^(In those ro
203e0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 utines that have
203f0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 a fourth argume
20400 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 nt, its value is
20410 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
20420 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 f bytes in the p
20430 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 arameter. To be
20440 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 clear: the valu
20450 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
20460 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f er of <u>bytes</
20470 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c u> in the value,
20480 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
20490 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e of characters.)^
204a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 .** ^If the four
204b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
204c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 negative, the le
204d0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 ngth of the stri
204e0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d ng is.** the num
204f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
20500 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
20510 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
20520 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
20530 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
20540 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
20550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
20560 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
20570 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
20580 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
20590 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
205a0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
205b0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
205c0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
205d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e shed with it. ^
205e0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
205f0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 s called.** to d
20600 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
20610 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 OB or string eve
20620 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f n if the call to
20630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
20640 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 ob(),.** sqlite3
20650 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 _bind_text(), or
20660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
20670 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a xt16() fails. .
20680 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
20690 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
206a0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
206b0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
206c0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
206d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
206e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
206f0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
20700 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
20710 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
20720 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e o be freed..** ^
20730 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
20740 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
20750 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
20760 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
20770 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
20780 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
20790 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
207a0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
207b0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
207c0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
207d0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
207e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
207f0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f nd_zeroblob() ro
20800 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c utine binds a BL
20810 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 OB of length N t
20820 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 hat.** is filled
20830 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e with zeroes. ^
20840 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 A zeroblob uses
20850 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f a fixed amount o
20860 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 f memory.** (jus
20870 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 t an integer to
20880 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 hold its size) w
20890 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 hile it is being
208a0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a processed..** Z
208b0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 eroblobs are int
208c0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 ended to serve a
208d0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 s placeholders f
208e0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a or BLOBs whose.*
208f0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 * content is lat
20900 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 er written using
20910 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
20920 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
20930 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 ntal BLOB I/O] r
20940 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e outines..** ^A n
20950 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f egative value fo
20960 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 r the zeroblob r
20970 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f esults in a zero
20980 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a -length BLOB..**
20990 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 .** ^If any of t
209a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
209b0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 *() routines are
209c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
209d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 ULL pointer.** f
209e0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 or the [prepared
209f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 statement] or w
20a00 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 ith a prepared s
20a10 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 tatement for whi
20a20 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 ch.** [sqlite3_s
20a30 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 tep()] has been
20a40 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 called more rece
20a50 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 ntly than [sqlit
20a60 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 e3_reset()],.**
20a70 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 then the call wi
20a80 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
20a90 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 E_MISUSE]. If a
20aa0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ny sqlite3_bind_
20ab0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 ().** routine is
20ac0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 passed a [prepa
20ad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
20ae0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e hat has been fin
20af0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 alized, the.** r
20b00 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
20b10 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
20b20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e harmful..**.** ^
20b30 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
20b40 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
20b50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20b60 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 ] routine..** ^U
20b70 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 nbound parameter
20b80 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
20b90 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a d as NULL..**.**
20ba0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
20bb0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 nd_* routines re
20bc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
20bd0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 on success or a
20be0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 n.** [error code
20bf0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f ] if anything go
20c00 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 es wrong..** ^[S
20c10 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 QLITE_RANGE] is
20c20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
20c30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 parameter.** ind
20c40 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
20c50 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f ge. ^[SQLITE_NO
20c60 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
20c70 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 if malloc() fai
20c80 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ls..**.** See al
20c90 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
20ca0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
20cb0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
20cc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
20cd0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
20ce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
20cf0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
20d00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
20d10 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
20d20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
20d30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
20d40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
20d50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
20d60 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
20d70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
20d80 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
20d90 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
20da0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
20db0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
20dc0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
20dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
20de0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
20df0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
20e00 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
20e10 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
20e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
20e30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
20e40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
20e50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
20e60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
20e70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
20e80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
20e90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
20ea0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
20eb0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
20ec0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
20ed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
20ee0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
20ef0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
20f00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
20f10 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
20f20 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
20f30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20f40 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
20f50 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a Parameters.**.*
20f60 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
20f70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 can be used to f
20f80 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
20f90 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 f [SQL parameter
20fa0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 s].** in a [prep
20fb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
20fc0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 SQL parameters
20fd0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 are tokens of t
20fe0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 he.** form "?",
20ff0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 "?NNN", ":AAA",
21000 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 "$AAA", or "@AAA
21010 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a " that serve as.
21020 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 ** placeholders
21030 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 for values that
21040 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e are [sqlite3_bin
21050 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a d_blob | bound].
21060 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 ** to the parame
21070 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 ters at a later
21080 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 time..**.** ^(Th
21090 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 is routine actua
210a0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
210b0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 index of the lar
210c0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 gest (rightmost)
210d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 .** parameter. F
210e0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
210f0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
21100 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
21110 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 o the.** number
21120 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 of unique parame
21130 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
21140 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
21150 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a form are used,.
21160 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 ** there may be
21170 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 gaps in the list
21180 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
21190 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
211a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
211b0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
211c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
211d0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a er_name()], and.
211e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
211f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
21200 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
21210 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
21220 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 er_count(sqlite3
21230 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
21240 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
21250 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 f A Host Paramet
21260 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 er.**.** ^The sq
21270 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
21280 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 eter_name(P,N) i
21290 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
212a0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
212b0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 the N-th [SQL pa
212c0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
212d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
212e0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c ent] P..** ^(SQL
212f0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
21300 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f he form "?NNN" o
21310 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 r ":AAA" or "@AA
21320 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 A" or "$AAA".**
21330 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 have a name whic
21340 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 h is the string
21350 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 "?NNN" or ":AAA"
21360 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 or "@AAA" or "$
21370 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 AAA".** respecti
21380 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 vely..** In othe
21390 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 r words, the ini
213a0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 tial ":" or "$"
213b0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a or "@" or "?".**
213c0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 is included as
213d0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 part of the name
213e0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 .)^.** ^Paramete
213f0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
21400 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c ?" without a fol
21410 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 lowing integer h
21420 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 ave no name.** a
21430 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 nd are referred
21440 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 to as "nameless"
21450 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 or "anonymous p
21460 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
21470 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 * ^The first hos
21480 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 t parameter has
21490 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e an index of 1, n
214a0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ot 0..**.** ^If
214b0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f the value N is o
214c0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 ut of range or i
214d0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d f the N-th param
214e0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c eter is.** namel
214f0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 ess, then NULL i
21500 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 s returned. ^Th
21510 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
21520 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 g is.** always i
21530 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 n UTF-8 encoding
21540 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d even if the nam
21550 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 ed parameter was
21560 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 .** originally s
21570 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d pecified as UTF-
21580 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 16 in [sqlite3_p
21590 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a repare16()] or.*
215a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
215b0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
215c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
215d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
215e0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
215f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
21600 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
21610 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
21620 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
21630 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
21640 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
21650 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
21660 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
21670 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
21680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
21690 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
216a0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
216b0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 Name.**.** ^Ret
216c0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 urn the index of
216d0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
216e0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 r given its name
216f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 . ^The.** index
21700 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
21710 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 is suitable for
21720 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e use as the secon
21730 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
21740 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
21750 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
21760 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a d()]. ^A zero.*
21770 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 * is returned if
21780 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 no matching par
21790 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e ameter is found.
217a0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 ^The parameter
217b0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
217c0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
217d0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
217e0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
217f0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
21800 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
21810 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
21820 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
21830 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
21840 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
21850 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
21860 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
21870 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
21880 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
21890 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
218a0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
218b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
218c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
218d0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
218e0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
218f0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
21900 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
21910 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
21920 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
21930 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 ment.**.** ^Cont
21940 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 rary to the intu
21950 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b ition of many, [
21960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
21970 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a does not reset.
21980 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
21990 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 bind_blob | bind
219a0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 ings] on a [prep
219b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
219c0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f .** ^Use this ro
219d0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
219e0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
219f0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 rs to NULL..*/.i
21a00 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
21a10 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
21a20 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
21a30 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
21a40 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
21a50 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
21a60 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e ** ^Return the n
21a70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
21a80 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
21a90 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 et returned by t
21aa0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
21ab0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 statement]. ^Thi
21ac0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
21ad0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 s 0 if pStmt is
21ae0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d an SQL.** statem
21af0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
21b00 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
21b10 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 or example an [U
21b20 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 PDATE])..**.** S
21b30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
21b40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 3_data_count()].
21b50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
21b60 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 olumn_count(sqli
21b70 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
21b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
21b90 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 F: Column Names
21ba0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
21bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
21bc0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
21bd0 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
21be0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
21bf0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
21c00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
21c10 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
21c20 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 nt. ^The sqlite
21c30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
21c40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
21c50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
21c60 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
21c70 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
21c80 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
21c90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
21ca0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
21cb0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
21cc0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
21cd0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 string. ^The f
21ce0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
21cf0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
21d00 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
21d10 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
21d20 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
21d30 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e ment. ^The secon
21d40 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
21d50 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d he.** column num
21d60 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d ber. ^The leftm
21d70 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
21d80 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mber 0..**.** ^T
21d90 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
21da0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
21db0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
21dc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
21dd0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
21de0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
21df0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
21e00 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e ] or until the n
21e10 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
21e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
21e30 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
21e40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
21e50 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
21e60 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 mn..**.** ^If sq
21e70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
21e80 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
21e90 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
21ea0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
21eb0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
21ec0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
21ed0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
21ee0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
21ef0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
21f00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
21f10 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 ^The name of a
21f20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
21f30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
21f40 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f e "AS" clause fo
21f50 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e r.** that column
21f60 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e , if there is an
21f70 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 AS clause. If
21f80 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 there is no AS c
21f90 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 lause.** then th
21fa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
21fb0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 lumn is unspecif
21fc0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e ied and may chan
21fd0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 ge from.** one r
21fe0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
21ff0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
22000 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
22010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
22020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22030 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
22040 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
22050 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
22060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
22070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22080 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
22090 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
220a0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 lt.**.** ^These
220b0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 routines provide
220c0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 a means to dete
220d0 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 rmine the databa
220e0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a se, table, and.*
220f0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 * table column t
22100 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 hat is the origi
22110 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 n of a particula
22120 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 r result column
22130 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 in.** [SELECT] s
22140 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 tatement..** ^Th
22150 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
22160 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
22170 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
22180 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
22190 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
221a0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
221b0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 ^The _database
221c0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
221d0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
221e0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 e name, the _tab
221f0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 le_ routines ret
22200 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 urn the table na
22210 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f me, and.** the o
22220 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 rigin_ routines
22230 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d return the colum
22240 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 n name..** ^The
22250 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
22260 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
22270 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
22280 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 tement] is destr
22290 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 oyed.** using [s
222a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
222b0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
222c0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
222d0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a is requested.**
222e0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 again in a diff
222f0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a erent encoding..
22300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 **.** ^The names
22310 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
22320 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
22330 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
22340 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
22350 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
22360 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 n..**.** ^The fi
22370 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
22380 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
22390 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
223a0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
223b0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
223c0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
223d0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 on about the Nth
223e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 result column r
223f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 eturned by.** th
22400 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 e statement, whe
22410 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
22420 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
22430 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 ment..** ^The le
22440 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
22450 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 s column 0 for t
22460 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
22470 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 *.** ^If the Nth
22480 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
22490 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
224a0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
224b0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
224c0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
224d0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
224e0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
224f0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
22500 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 ** NULL. ^These
22510 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 routine might a
22520 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 lso return NULL
22530 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
22540 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 cation error.**
22550 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 occurs. ^Otherw
22560 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
22570 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
22580 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
22590 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 se, table,.** or
225a0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
225b0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
225c0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
225d0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 rom..**.** ^As w
225e0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
225f0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
22600 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 whose names end
22610 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
22620 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f n.** UTF-16 enco
22630 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 ded strings and
22640 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 the other functi
22650 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 ons return UTF-8
22660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 ..**.** ^These A
22670 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
22680 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
22690 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
226a0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
226b0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
226c0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
226d0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
226e0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 mbol..**.** If t
226f0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
22700 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
22710 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
22720 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
22730 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
22740 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
22750 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
22760 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
22770 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
22780 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
22790 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
227a0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
227b0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 e or more.** [sq
227c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
227d0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c abase_name | col
227e0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 umn metadata int
227f0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 erfaces].** for
22800 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
22810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
22820 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
22830 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ** at the same t
22840 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
22850 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
22860 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 ed..*/.const cha
22870 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
22880 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
22890 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
228a0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
228b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
228c0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
228d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
228e0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
228f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
22900 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
22910 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
22920 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
22930 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
22940 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
22950 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
22960 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
22970 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
22980 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
22990 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
229a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
229b0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c rigin_name16(sql
229c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
229d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
229e0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 : Declared Datat
229f0 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 ype Of A Query R
22a00 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 esult.**.** ^(Th
22a10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
22a20 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 r is a [prepared
22a30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
22a40 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
22a50 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 t is a [SELECT]
22a60 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 statement and th
22a70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
22a80 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 the.** returned
22a90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
22aa0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 at [SELECT] is a
22ab0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
22ac0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
22ad0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
22ae0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
22af0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
22b00 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
22b10 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e s returned.)^ ^
22b20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
22b30 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
22b40 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
22b50 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
22b60 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
22b70 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
22b80 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 rned..** ^The re
22b90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
22ba0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e always UTF-8 en
22bb0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 coded..**.** ^(F
22bc0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 or example, give
22bd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 n the database s
22be0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 chema:.**.** CRE
22bf0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 ATE TABLE t1(c1
22c00 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 VARIANT);.**.**
22c10 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e and the followin
22c20 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 g statement to b
22c30 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a e compiled:.**.*
22c40 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
22c50 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
22c60 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ** this routine
22c70 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 would return the
22c80 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 string "VARIANT
22c90 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 " for the second
22ca0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d result.** colum
22cb0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 n (i==1), and a
22cc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
22cd0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c the first resul
22ce0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e t column (i==0).
22cf0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
22d00 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
22d10 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
22d20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 ^So just because
22d30 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 a column.** is
22d40 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 declared to cont
22d50 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ain a particular
22d60 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d type does not m
22d70 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ean that the.**
22d80 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 data stored in t
22d90 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 hat column is of
22da0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
22db0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a pe. SQLite is.*
22dc0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 * strongly typed
22dd0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 , but the typing
22de0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 is dynamic not
22df0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a static. ^Type.*
22e00 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 * is associated
22e10 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 with individual
22e20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 values, not with
22e30 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a the containers.
22e40 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ** used to hold
22e50 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f those values..*/
22e60 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
22e70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
22e80 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
22e90 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
22ea0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
22eb0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 umn_decltype16(s
22ec0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
22ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
22ee0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 EF: Evaluate An
22ef0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
22f00 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 .** After a [pre
22f10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22f20 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 has been prepar
22f30 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a ed using either.
22f40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
22f50 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
22f60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
22f70 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
22f80 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
22f90 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
22fa0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
22fb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22fc0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 16()], this func
22fd0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 tion.** must be
22fe0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
22ff0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c re times to eval
23000 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 uate the stateme
23010 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 nt..**.** The de
23020 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 tails of the beh
23030 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c avior of the sql
23040 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 ite3_step() inte
23050 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 rface depend.**
23060 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 on whether the s
23070 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 tatement was pre
23080 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 pared using the
23090 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 newer "v2" inter
230a0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 face.** [sqlite3
230b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
230c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
230d0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 are16_v2()] or t
230e0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a he older legacy.
230f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 ** interface [sq
23100 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
23110 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
23120 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 epare16()]. The
23130 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e use of the.** n
23140 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 ew "v2" interfac
23150 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
23160 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 for new applica
23170 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 tions but the le
23180 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
23190 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 e will continue
231a0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
231b0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c .**.** ^In the l
231c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
231d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
231e0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 e will be either
231f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a [SQLITE_BUSY],.
23200 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
23210 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
23220 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
23230 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
23240 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 E]..** ^With the
23250 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
23260 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 any of the othe
23270 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d r [result codes]
23280 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
23290 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d result codes] m
232a0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 ight be returned
232b0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 as well..**.**
232c0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d ^[SQLITE_BUSY] m
232d0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 eans that the da
232e0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 tabase engine wa
232f0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 s unable to acqu
23300 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ire the.** datab
23310 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 ase locks it nee
23320 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 ds to do its job
23330 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 . ^If the state
23340 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 ment is a [COMMI
23350 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 T].** or occurs
23360 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 outside of an ex
23370 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
23380 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e on, then you can
23390 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 retry the.** st
233a0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 atement. If the
233b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f statement is no
233c0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 t a [COMMIT] and
233d0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
233e0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
233f0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
23400 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
23410 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
23420 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
23430 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
23440 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
23450 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
23460 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
23470 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
23480 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
23490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
234a0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
234b0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
234c0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
234d0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
234e0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
234f0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
23500 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
23510 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
23520 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
23530 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
23540 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
23550 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
23560 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
23570 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
23580 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
23590 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
235a0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
235b0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
235c0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
235d0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
235e0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
235f0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
23600 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
23610 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
23620 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
23630 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
23640 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
23650 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
23660 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
23670 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
23680 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
23690 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
236a0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
236b0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
236c0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
236d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
236e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
236f0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
23700 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
23710 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
23720 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
23730 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
23740 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
23750 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
23760 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
23770 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
23780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
23790 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
237a0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
237b0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
237c0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
237d0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
237e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
237f0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
23800 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
23810 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
23820 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
23830 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
23840 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
23850 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
23860 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
23870 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
23880 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
23890 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
238a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
238b0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
238c0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
238d0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
238e0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
238f0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
23900 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
23910 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
23920 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
23930 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
23940 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
23950 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
23960 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
23970 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
23980 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
23990 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
239a0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
239b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
239c0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
239d0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
239e0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
239f0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
23a00 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
23a10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
23a20 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
23a30 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 69 ding 3.6.23.1, i
23a40 74 20 77 61 73 20 72 65 71 75 69 72 65 64 0a 2a t was required.*
23a50 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f * after sqlite3_
23a60 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 step() returned
23a70 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 anything other t
23a80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
23a90 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 that.** [sqlite
23aa0 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20 63 61 3_reset()] be ca
23ab0 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e 79 20 lled before any
23ac0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
23ad0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 ation of.** sqli
23ae0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 te3_step(). Fai
23af0 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b lure to invoke [
23b00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
23b10 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 6f 75 in this way wou
23b20 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ld.** result in
23b30 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 an [SQLITE_MISUS
23b40 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 73 E] return from s
23b50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
23b60 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76 65 72 But after.** ver
23b70 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 sion 3.6.23.1, s
23b80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 qlite3_step() be
23b90 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c gan calling [sql
23ba0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 0a 2a ite3_reset()] .*
23bb0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
23bc0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
23bd0 61 6e 63 65 20 72 61 74 68 65 72 20 74 68 61 6e ance rather than
23be0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
23bf0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a 2a 2a TE_MISUSE]. .**
23c00 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
23c10 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
23c20 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
23c30 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
23c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
23c50 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
23c60 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
23c70 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
23c80 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
23c90 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
23ca0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
23cb0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
23cc0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
23cd0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
23ce0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
23cf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
23d00 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
23d10 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
23d20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
23d30 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
23d40 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
23d50 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
23d60 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
23d70 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
23d80 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
23d90 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
23da0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
23db0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
23dc0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
23dd0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
23de0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
23df0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
23e00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
23e10 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
23e20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
23e30 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
23e40 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
23e50 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
23e60 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
23e70 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
23e80 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
23e90 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
23ea0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
23eb0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
23ec0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
23ed0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
23ee0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
23ef0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
23f00 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ended..*/.int sq
23f10 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
23f20 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
23f30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
23f40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
23f50 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
23f60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
23f70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 _data_count(P) i
23f80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
23f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
23fa0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
23fb0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
23fc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
23fd0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
23fe0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 ement] P..** ^If
23ff0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
24000 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 ent P does not h
24010 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 ave results read
24020 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 y to return.** (
24030 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 via calls to the
24040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24050 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 _int | sqlite3_c
24060 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a olumn_*()] of.**
24070 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 interfaces) the
24080 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 n sqlite3_data_c
24090 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 ount(P) returns
240a0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 0..** ^The sqlit
240b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
240c0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 routine also re
240d0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 turns 0 if P is
240e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
240f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
24100 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
24110 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
24120 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
24130 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
24140 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
24150 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d CAPI3REF: Fundam
24160 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a ental Datatypes.
24170 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
24180 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e ITE_TEXT.**.** ^
24190 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 (Every value in
241a0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
241b0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
241c0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
241d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
241e0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
241f0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
24200 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
24210 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
24220 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
24230 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
24240 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
24250 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 l>)^.**.** These
24260 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 constants are c
24270 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 odes for each of
24280 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a those types..**
24290 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
242a0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f e SQLITE_TEXT co
242b0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 nstant was also
242c0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 used in SQLite v
242d0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 ersion 2.** for
242e0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 a completely dif
242f0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 ferent meaning.
24300 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c Software that l
24310 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 inks against bot
24320 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 h.** SQLite vers
24330 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 ion 2 and SQLite
24340 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c version 3 shoul
24350 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 d use SQLITE3_TE
24360 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 XT, not.** SQLIT
24370 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 E_TEXT..*/.#defi
24380 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 ne SQLITE_INTEGE
24390 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c R 1.#define SQL
243a0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 ITE_FLOAT 2.#
243b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c define SQLITE_BL
243c0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 OB 4.#define
243d0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 SQLITE_NULL
243e0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5.#ifdef SQLITE
243f0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 _TEXT.# undef SQ
24400 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a LITE_TEXT.#else.
24410 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
24420 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 TEXT 3.#endi
24430 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 f.#define SQLITE
24440 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 3_TEXT 3../*
24450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
24460 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d sult Values From
24470 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 A Query.** KEYW
24480 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 ORDS: {column ac
24490 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a cess functions}.
244a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
244b0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 ines form the "r
244c0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 esult set" inter
244d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 face..**.** ^The
244e0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
244f0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
24500 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f bout a single co
24510 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 lumn of the curr
24520 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f ent.** result ro
24530 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e w of a query. ^
24540 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 In every case th
24550 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
24560 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a is a pointer.**
24570 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 to the [prepare
24580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
24590 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 t is being evalu
245a0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 ated (the [sqlit
245b0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 e3_stmt*].** tha
245c0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 t was returned f
245d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 rom [sqlite3_pre
245e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e pare_v2()] or on
245f0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 e of its variant
24600 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 s).** and the se
24610 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
24620 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
24630 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 e column for whi
24640 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ch information.*
24650 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 * should be retu
24660 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d rned. ^The leftm
24670 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ost column of th
24680 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 e result set has
24690 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a the index 0..**
246a0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 ^The number of
246b0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
246c0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 esult can be det
246d0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a ermined using.**
246e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
246f0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a _count()]..**.**
24700 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
24710 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
24720 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 urrently point t
24730 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f o a valid row, o
24740 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r if the.** colu
24750 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
24760 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
24770 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
24780 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 d..** These rout
24790 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ines may only be
247a0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
247b0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
247c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
247d0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
247e0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
247f0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a W] and neither.*
24800 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
24810 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 ()] nor [sqlite3
24820 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 _finalize()] hav
24830 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 e been called su
24840 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 bsequently..** I
24850 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 f any of these r
24860 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
24870 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
24880 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
24890 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
248a0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b ze()] or after [
248b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
248c0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 has returned.**
248d0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
248e0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
248f0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ], the results a
24900 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
24910 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 If [sqlite3_ste
24920 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
24930 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
24940 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
24950 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 ].** are called
24960 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 from a different
24970 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e thread while an
24980 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
24990 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 nes.** are pendi
249a0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 ng, then the res
249b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
249c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
249d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
249e0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 pe() routine ret
249f0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c urns the.** [SQL
24a00 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
24a10 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 tatype code] for
24a20 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 the initial dat
24a30 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 a type.** of the
24a40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 result column.
24a50 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 ^The returned v
24a60 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b alue is one of [
24a70 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
24a80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 .** [SQLITE_FLOA
24a90 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
24aa0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d ], [SQLITE_BLOB]
24ab0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c , or [SQLITE_NUL
24ac0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a L]. The value.*
24ad0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
24ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
24af0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e e() is only mean
24b00 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 ingful if no typ
24b10 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 e.** conversions
24b20 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 have occurred a
24b30 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f s described belo
24b40 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 w. After a type
24b50 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 conversion,.**
24b60 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
24b70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
24b80 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 lumn_type() is u
24b90 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 ndefined. Futur
24ba0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 e.** versions of
24bb0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e SQLite may chan
24bc0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ge the behavior
24bd0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d of sqlite3_colum
24be0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c n_type().** foll
24bf0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e owing a type con
24c00 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e version..**.** ^
24c10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
24c20 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 a BLOB or UTF-8
24c30 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
24c40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
24c50 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 bytes().** routi
24c60 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
24c70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
24c80 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
24c90 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
24ca0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
24cb0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 F-16 string, the
24cc0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
24cd0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 _bytes() convert
24ce0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
24cf0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 to UTF-8 and the
24d00 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
24d10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
24d20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
24d30 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
24d40 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
24d50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
24d60 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
24d70 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
24d80 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
24d90 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 ue to a UTF-8 st
24da0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
24db0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
24dc0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
24dd0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
24de0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c he result is NUL
24df0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f L, then sqlite3_
24e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 column_bytes() r
24e10 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
24e20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
24e30 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
24e40 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 TF-16 string the
24e50 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
24e60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a lumn_bytes16().*
24e70 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
24e80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
24e90 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
24ea0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
24eb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
24ec0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
24ed0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
24ee0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
24ef0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
24f00 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 string to UTF-1
24f10 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6 and then retur
24f20 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
24f30 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
24f40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
24f50 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
24f60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
24f70 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a _bytes16() uses.
24f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
24f90 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
24fa0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
24fb0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
24fc0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
24fd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
24fe0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
24ff0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
25000 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
25010 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
25020 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 mn_bytes16() ret
25030 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
25040 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
25050 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
25060 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
25070 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 ] and .** [sqlit
25080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
25090 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 6()] do not incl
250a0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
250b0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 minators at the
250c0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
250d0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 ring. ^For clar
250e0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 ity: the values
250f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
25100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
25110 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c ytes()] and [sql
25120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
25130 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e s16()] are the n
25140 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
25150 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
25160 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
25170 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
25180 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 *.** ^Strings re
25190 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
251a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
251b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
251c0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
251d0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
251e0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
251f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero terminated.
25200 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 ^The return.**
25210 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 value from sqlit
25220 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
25230 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 for a zero-leng
25240 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c th BLOB is a NUL
25250 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
25260 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 ^The object ret
25270 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
25280 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
25290 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 ] is an.** [unpr
252a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
252b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 value] object.
252c0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 An unprotected s
252d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
252e0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 ect.** may only
252f0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 be used with [sq
25300 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
25310 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
25320 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
25330 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 ..** If the [unp
25340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25350 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 _value] object r
25360 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
25370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
25380 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 lue()] is used i
25390 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c n any other way,
253a0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 including calls
253b0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 .** to routines
253c0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 like [sqlite3_va
253d0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c lue_int()], [sql
253e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
253f0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
25400 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
25410 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ], then the beha
25420 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
25430 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
25440 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 outines attempt
25450 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
25460 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f alue where appro
25470 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a priate. ^For.**
25480 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
25490 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
254a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 entation is FLOA
254b0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 T and a text res
254c0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 ult.** is reques
254d0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e ted, [sqlite3_sn
254e0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 printf()] is use
254f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
25500 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 perform the.** c
25510 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 onversion automa
25520 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 tically. ^(The
25530 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 following table
25540 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 details the conv
25550 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 ersions.** that
25560 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a are applied:.**.
25570 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
25580 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
25590 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
255a0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 > Internal<br>Ty
255b0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 pe <th> Requeste
255c0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 d<br>Type <th>
255d0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a Conversion.**.**
255e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
255f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
25600 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
25610 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 0.** <tr><td>
25620 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c NULL <td> FL
25630 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 OAT <td> Resu
25640 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 lt is 0.0.** <tr
25650 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
25660 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
25670 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
25680 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
25690 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
256a0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
256b0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
256c0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
256d0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
256e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
256f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
25700 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 integer to float
25710 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
25720 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 EGER <td> TEX
25730 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
25740 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
25750 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e integer.** <tr>
25760 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
25770 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
25780 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 > Same as INTEGE
25790 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c R->TEXT.** <tr><
257a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
257b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
257c0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c Convert from fl
257d0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a oat to integer.*
257e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
257f0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
25800 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
25810 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
25820 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
25830 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
25840 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
25850 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 me as FLOAT->TEX
25860 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 T.** <tr><td> T
25870 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
25880 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 GER <td> Use a
25890 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
258a0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
258b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 FLOAT <td> U
258c0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 se atof().** <tr
258d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
258e0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
258f0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
25900 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
25910 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
25920 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
25930 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
25940 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
25950 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
25960 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
25970 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
25980 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a hen use atof().*
25990 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
259a0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
259b0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
259c0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
259d0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
259e0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
259f0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ote>)^.**.** The
25a00 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
25a10 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
25a20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
25a30 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
25a40 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
25a50 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
25a60 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
25a70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
25a80 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
25a90 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
25aa0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
25ab0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
25ac0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
25ad0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
25ae0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
25af0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
25b00 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
25b10 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
25b20 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
25b30 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
25b40 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
25b50 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
25b60 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
25b70 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
25b80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
25b90 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
25ba0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
25bb0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
25bc0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
25bd0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
25be0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
25bf0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
25c00 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
25c10 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
25c20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
25c30 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
25c40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
25c50 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
25c60 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
25c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
25c80 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
25c90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
25ca0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
25cb0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
25cc0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
25cd0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
25ce0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
25cf0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
25d00 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
25d10 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
25d20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
25d30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
25d40 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
25d50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
25d60 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
25d70 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
25d80 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
25d90 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
25da0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
25db0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
25dc0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
25dd0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
25de0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
25df0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
25e00 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
25e10 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
25e20 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
25e30 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
25e40 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
25e50 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
25e60 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
25e70 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
25e80 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
25e90 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
25ea0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
25eb0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
25ec0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
25ed0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
25ee0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
25ef0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
25f00 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
25f10 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
25f20 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
25f30 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
25f40 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
25f50 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
25f60 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
25f70 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
25f80 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
25f90 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
25fa0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
25fb0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
25fc0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
25fd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
25fe0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
25ff0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
26000 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
26010 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
26020 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
26030 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
26040 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
26050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
26060 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
26070 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
26080 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
26090 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
260a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
260b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
260c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
260d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
260e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
260f0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
26100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
26110 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
26120 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
26130 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
26140 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
26150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
26160 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
26170 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
26180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
26190 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
261a0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
261b0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
261c0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
261d0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
261e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
261f0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
26200 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
26210 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
26220 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
26230 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
26240 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
26250 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
26260 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
26270 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
26280 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
26290 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
262a0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
262b0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
262c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
262d0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
262e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
262f0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
26300 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
26310 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
26320 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
26330 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
26340 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
26350 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
26360 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
26370 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
26380 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
26390 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
263a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
263b0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
263c0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
263d0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
263e0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
263f0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
26400 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
26410 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
26420 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rned.** [sqlite3
26430 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
26440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
26450 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
26460 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
26470 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
26480 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
26490 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
264a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
264b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
264c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
264d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
264e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
264f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
26500 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
26510 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
26520 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
26530 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
26540 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
26550 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
26560 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
26570 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
26580 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
26590 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
265a0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 )^.*/.const void
265b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
265c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
265d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
265e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
265f0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
26600 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
26610 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
26620 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
26630 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
26640 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 iCol);.double s
26650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
26660 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(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 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
266a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
266b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
266c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
266d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
266e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
266f0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
26700 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
26710 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
26720 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
26730 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
26740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
26750 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
26760 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
26770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
26780 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
26790 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
267a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
267b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
267c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
267d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
267e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
267f0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
26800 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
26810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 te3_finalize() f
26830 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
26840 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 d to delete a [p
26850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26860 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d t]..** ^If the m
26870 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
26880 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 ation of the sta
26890 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 tement encounter
268a0 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a ed no errors or.
268b0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 ** or if the sta
268c0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 tement is never
268d0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 been evaluated,
268e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e then sqlite3_fin
268f0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a alize() returns.
26900 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e ** SQLITE_OK. ^
26910 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
26920 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 nt evaluation of
26930 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 statement S fai
26940 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c led, then.** sql
26950 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
26960 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 returns the app
26970 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
26980 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
26990 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
269a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
269b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
269c0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 ) routine can be
269d0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 called at any p
269e0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 oint during.** t
269f0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 he life cycle of
26a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26a10 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f ment] S:.** befo
26a20 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 re statement S i
26a30 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 s ever evaluated
26a40 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f , after.** one o
26a50 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 r more calls to
26a60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
26a70 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 ], or after any
26a80 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 call.** to [sqli
26a90 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 te3_step()] rega
26aa0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
26ab0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 r or not the sta
26ac0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f tement has.** co
26ad0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
26ae0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 n..**.** ^Invoki
26af0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ng sqlite3_final
26b00 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 ize() on a NULL
26b10 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 pointer is a har
26b20 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a mless no-op..**.
26b30 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
26b40 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 on must finalize
26b50 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 every [prepared
26b60 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f statement] in o
26b70 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a rder to avoid.**
26b80 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e resource leaks.
26b90 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f It is a grievo
26ba0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 us error for the
26bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
26bc0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 try to use.** a
26bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
26be0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
26bf0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 been finalized.
26c00 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 Any use of a pr
26c10 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
26c20 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
26c30 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 been finalized
26c40 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e can result in un
26c50 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 defined and.** u
26c60 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
26c70 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 ior such as segf
26c80 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 aults and heap c
26c90 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e orruption..*/.in
26ca0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 t sqlite3_finali
26cb0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
26cc0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
26cd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
26ce0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
26cf0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
26d00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
26d10 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 set() function i
26d20 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 s called to rese
26d30 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 t a [prepared st
26d40 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
26d50 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ct back to its i
26d60 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 nitial state, re
26d70 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 ady to be re-exe
26d80 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 cuted..** ^Any S
26d90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
26da0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
26db0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
26dc0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
26dd0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
26de0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
26df0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
26e00 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
26e10 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
26e20 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
26e30 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
26e40 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
26e50 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
26e60 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
26e70 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
26e80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26e90 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 t] S.** back to
26ea0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
26eb0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a its program..**
26ec0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
26ed0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
26ee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
26ef0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 ] for the.** [pr
26f00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26f10 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
26f20 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
26f30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f LITE_DONE],.** o
26f40 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 r if [sqlite3_st
26f50 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 ep(S)] has never
26f60 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c before been cal
26f70 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 led on S,.** the
26f80 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
26f90 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 (S)] returns [SQ
26fa0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
26fb0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
26fc0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
26fd0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
26fe0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
26ff0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
27000 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
27010 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c or, then.** [sql
27020 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
27030 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
27040 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
27050 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b e]..**.** ^The [
27060 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
27070 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
27080 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
27090 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 values.** of any
270a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
270b0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
270c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
270d0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
270e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 int sqlite3_rese
270f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
27100 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
27110 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
27120 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
27130 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
27140 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
27150 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
27160 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
27170 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
27180 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
27190 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
271a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
271b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
271c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ons}.**.** ^Thes
271d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c e functions (col
271e0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 lectively known
271f0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 as "function cre
27200 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 ation routines")
27210 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 .** are used to
27220 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e add SQL function
27230 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 s or aggregates
27240 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 or to redefine t
27250 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f he behavior.** o
27260 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 f existing SQL f
27270 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
27280 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c egates. The onl
27290 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 y differences be
272a0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 tween.** these r
272b0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 outines are the
272c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 text encoding ex
272d0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 pected for.** th
272e0 65 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 e the second par
272f0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 ameter (the name
27300 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
27310 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a being created).
27320 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 ** and the prese
27330 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f nce or absence o
27340 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 f a destructor c
27350 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 allback for.** t
27360 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
27370 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ata pointer..**.
27380 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
27390 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
273a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
273b0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
273c0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
273d0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
273e0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 . ^If an applic
273f0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 ation uses more
27400 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
27410 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
27420 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e then application
27430 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
27440 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 ctions must be a
27450 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 dded.** to each
27460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
27470 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ion separately..
27480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
27490 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
274a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
274b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
274c0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
274d0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 redefined. ^The
274e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
274f0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
27500 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 o 255 bytes in a
27510 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 UTF-8.** repres
27520 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 entation, exclus
27530 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d ive of the zero-
27540 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f terminator. ^No
27550 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 te that the name
27560 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 .** length limit
27570 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 is in UTF-8 byt
27580 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 es, not characte
27590 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 rs nor UTF-16 by
275a0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 tes. .** ^Any a
275b0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
275c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
275d0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
275e0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
275f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
27600 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e being returned.
27610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
27620 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 d parameter (nAr
27630 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d g).** is the num
27640 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
27650 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 that the SQL fu
27660 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
27670 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 regate takes. ^I
27680 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 f this parameter
27690 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 is -1, then the
276a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
276b0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
276c0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
276d0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 r of arguments b
276e0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 etween 0 and the
276f0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 limit.** set by
27700 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
27710 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 ([SQLITE_LIMIT_F
27720 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 UNCTION_ARG]).
27730 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 If the third.**
27740 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 parameter is les
27750 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 s than -1 or gre
27760 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 ater than 127 th
27770 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
27780 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e is.** undefined.
27790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 .**.** ^The four
277a0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 th parameter, eT
277b0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 extRep, specifie
277c0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 s what.** [SQLIT
277d0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e E_UTF8 | text en
277e0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c coding] this SQL
277f0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 function prefer
27800 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 s for.** its par
27810 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 ameters. Every
27820 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
27830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
27840 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b be able to work
27850 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 .** with UTF-8,
27860 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 UTF-16le, or UTF
27870 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 -16be. But some
27880 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
27890 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 may be.** more
278a0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f efficient with o
278b0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e ne encoding than
278c0 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 another. ^An a
278d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a pplication may.*
278e0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
278f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
27900 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
27910 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
27920 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 ) multiple.** ti
27930 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
27940 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 e function but w
27950 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 ith different va
27960 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 lues of eTextRep
27970 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 ..** ^When multi
27980 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
27990 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
279a0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 function are ava
279b0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a ilable, SQLite.*
279c0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 * will pick the
279d0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 one that involve
279e0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
279f0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 nt of data conve
27a00 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 rsion..** If the
27a10 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e re is only a sin
27a20 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 gle implementati
27a30 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f on which does no
27a40 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 t care what text
27a50 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 .** encoding is
27a60 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 used, then the f
27a70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 ourth argument s
27a80 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 hould be [SQLITE
27a90 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 _ANY]..**.** ^(T
27aa0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
27ab0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
27ac0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
27ad0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
27ae0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
27af0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
27b00 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
27b10 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
27b20 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 3_user_data()].)
27b30 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 76 ^.**.** ^The sev
27b40 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 enth, eighth and
27b50 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 ninth parameter
27b60 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
27b70 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
27b80 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
27b90 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
27ba0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
27bb0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
27bc0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
27bd0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
27be0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
27bf0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
27c00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
27c10 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
27c20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
27c30 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 ers must be pass
27c40 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
27c50 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
27c60 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
27c70 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
27c80 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
27c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
27ca0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
27cb0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
27cc0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 pointer must be
27cd0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
27ce0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
27cf0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
27d00 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
27d10 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
27d20 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c poiners for all
27d30 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a three function.
27d40 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a ** callbacks..**
27d50 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 74 65 6e .** ^(If the ten
27d60 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
27d70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
27d80 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 unction_v2() is
27d90 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 not NULL,.** the
27da0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 n it is destruct
27db0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
27dc0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
27dd0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 ter. .** The des
27de0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b tructor is invok
27df0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 ed when the func
27e00 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c tion is deleted,
27e10 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 either by being
27e20 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f .** overloaded o
27e30 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 r when the datab
27e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
27e50 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 loses.)^.** ^The
27e60 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 destructor is a
27e70 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 lso invoked if t
27e80 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
27e90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
27ea0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 ction_v2() fails
27eb0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 ..** ^When the d
27ec0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
27ed0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 ck of the tenth
27ee0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 parameter is inv
27ef0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 oked, it.** is p
27f00 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 assed a single a
27f10 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
27f20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 a copy of the a
27f30 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
27f40 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 .** pointer whic
27f50 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 h was the fifth
27f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
27f70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
27f80 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a tion_v2()..**.**
27f90 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 ^It is permitte
27fa0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
27fb0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
27fc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
27fd0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
27fe0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
27ff0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
28000 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
28010 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
28020 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
28030 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
28040 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 encodings. ^SQ
28050 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
28060 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
28070 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c ion that most cl
28080 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
28090 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
280a0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
280b0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 on is used. ^A
280c0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
280d0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e ntation with a n
280e0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e on-negative.** n
280f0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 Arg parameter is
28100 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 a better match
28110 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
28120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
28130 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 ith.** a negativ
28140 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 e nArg. ^A func
28150 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 tion where the p
28160 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
28170 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 coding.** matche
28180 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
28190 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 ncoding is a bet
281a0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 ter.** match tha
281b0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
281c0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
281d0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a is different. .
281e0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 ** ^A function w
281f0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
28200 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
28210 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
28220 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
28230 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
28240 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
28250 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
28260 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
28270 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
28280 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
28290 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e ** ^Built-in fun
282a0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
282b0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
282c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
282d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
282e0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 *.** ^An applica
282f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
28300 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
28310 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
28320 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
28330 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
28340 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
28350 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
28360 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
28370 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
28380 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
28390 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
283a0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
283b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
283c0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
283d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
283e0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
283f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
28400 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
28410 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
28420 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
28430 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
28440 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
28450 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
28460 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
28470 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
28480 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
28490 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
284a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
284b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
284c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
284d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
284e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
284f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
28500 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
28510 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
28520 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
28530 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
28540 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
28550 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
28560 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
28570 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
28580 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
28590 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
285a0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
285b0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
285c0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
285d0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
285e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
285f0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
28600 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
28610 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
28620 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
28630 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
28640 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
28650 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
28660 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
28670 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
28680 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
28690 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
286a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
286b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
286c0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
286d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
286e0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
286f0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
28700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28710 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
28720 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
28730 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
28740 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
28750 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
28760 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
28770 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
28780 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
28790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
287a0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 8 1.#d
287b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
287c0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 16LE 2.#d
287d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
287e0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 16BE 3.#d
287f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
28800 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
28810 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
28820 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
28830 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
28840 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
28850 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
28860 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 e_function only
28870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
28880 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 E_UTF16_ALIGNED
28890 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 8 /* sqlite3
288a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
288b0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a n only */../*.**
288c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 CAPI3REF: Depre
288d0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a cated Functions.
288e0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a ** DEPRECATED.**
288f0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
28900 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 ons are [depreca
28910 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 ted]. In order
28920 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 to maintain.** b
28930 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
28940 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 bility with olde
28950 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 r code, these fu
28960 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 nctions continue
28970 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f .** to be suppo
28980 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 rted. However,
28990 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
289a0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
289b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
289c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
289d0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 help encourage
289e0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a people to avoid.
289f0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 ** using these f
28a00 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 unctions, we are
28a10 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 not going to te
28a20 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 ll you what they
28a30 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 do..*/.#ifndef
28a40 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 SQLITE_OMIT_DEPR
28a50 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 ECATED.SQLITE_DE
28a60 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
28a70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
28a80 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e ount(sqlite3_con
28a90 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 text*);.SQLITE_D
28aa0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
28ab0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 lite3_expired(sq
28ac0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
28ad0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
28ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e int sqlite3_tran
28af0 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 sfer_bindings(sq
28b00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c lite3_stmt*, sql
28b10 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
28b20 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
28b30 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 nt sqlite3_globa
28b40 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b l_recover(void);
28b50 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
28b60 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f ED void sqlite3_
28b70 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 thread_cleanup(v
28b80 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 oid);.SQLITE_DEP
28b90 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
28ba0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
28bb0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 (void(*)(void*,s
28bc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 qlite3_int64,int
28bd0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f ),void*,sqlite3_
28be0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a int64);.#endif..
28bf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28c00 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 Obtaining SQL Fu
28c10 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 nction Parameter
28c20 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Values.**.** Th
28c30 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
28c40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
28c50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
28c60 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
28c70 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
28c80 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
28c90 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
28ca0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
28cb0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
28cc0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
28cd0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 e..**.** The xFu
28ce0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
28cf0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
28d00 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
28d10 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
28d20 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
28d30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
28d40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
28d50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
28d60 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
28d70 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
28d80 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
28d90 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
28da0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 egates..** The 4
28db0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
28dc0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
28dd0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
28de0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
28df0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
28e00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
28e10 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
28e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
28e30 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
28e40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
28e50 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
28e60 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
28e70 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
28e80 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
28e90 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
28ea0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
28eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
28ec0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
28ed0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
28ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
28ef0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
28f00 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
28f10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
28f20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
28f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
28f40 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
28f50 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
28f60 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 havior..**.** ^T
28f70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
28f80 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
28f90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
28fa0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
28fb0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
28fc0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 pt that these r
28fd0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
28fe0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
28ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
29000 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
29010 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
29020 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
29030 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
29040 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
29050 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
29060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
29070 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
29080 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
29090 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
290a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
290b0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
290c0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
290d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
290e0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
290f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
29100 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
29110 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
29120 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
29130 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
29140 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
29150 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
29160 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
29170 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
29180 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
29190 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
291a0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
291b0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
291c0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
291d0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
291e0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
291f0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
29200 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
29210 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
29220 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
29230 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
29240 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
29250 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
29260 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
29270 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
29280 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
29290 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
292a0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
292b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
292c0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
292d0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
292e0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
292f0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
29300 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
29310 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
29320 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
29330 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
29340 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
29350 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
29360 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
29370 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
29380 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
29390 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
293a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
293b0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
293c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
293d0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
293e0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
293f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
29400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
29410 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
29420 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
29430 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
29440 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
29450 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
29460 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
29470 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
29480 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
29490 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
294a0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
294b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
294c0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
294d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
294e0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
294f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
29500 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
29510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
29520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
29530 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
29540 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
29550 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
29560 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
29570 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
29580 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
29590 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
295a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
295b0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
295c0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
295d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
295e0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
295f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
29600 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
29610 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
29620 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
29630 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
29640 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
29650 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
29660 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
29670 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
29680 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
29690 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
296a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
296b0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
296c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
296d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
296e0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
296f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
29700 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
29710 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
29720 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
29730 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
29740 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
29750 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 n Context.**.**
29760 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 Implementations
29770 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c of aggregate SQL
29780 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 functions use t
29790 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 his.** routine t
297a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
297b0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 y for storing th
297c0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
297d0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
297e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 the sqlite3_agg
297f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
29800 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 ,N) routine is c
29810 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 alled .** for a
29820 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 particular aggre
29830 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 gate function, S
29840 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 QLite.** allocat
29850 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 es N of memory,
29860 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 zeroes out that
29870 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 memory, and retu
29880 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
29890 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f to the new memo
298a0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 ry. ^On second a
298b0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 nd subsequent ca
298c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
298d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
298e0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 ext() for the sa
298f0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
29900 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a ction instance,.
29910 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
29920 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
29930 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 Sqlite3_aggrega
29940 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 te_context() is
29950 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c normally.** call
29960 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
29970 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
29980 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 he xStep callbac
29990 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a k and then one.*
299a0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e * last time when
299b0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c the xFinal call
299c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e back is invoked.
299d0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 ^(When no rows
299e0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 match.** an agg
299f0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 regate query, th
29a00 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 e xStep() callba
29a10 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 ck of the aggreg
29a20 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ate function.**
29a30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
29a40 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 s never called a
29a50 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 nd xFinal() is c
29a60 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e alled exactly on
29a70 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 ce..** In those
29a80 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 cases, sqlite3_a
29a90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
29aa0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c () might be call
29ab0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 ed for the.** fi
29ac0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 rst time from wi
29ad0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e thin xFinal().)^
29ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
29af0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
29b00 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 ntext(C,N) routi
29b10 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ne returns a NUL
29b20 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 L pointer if N i
29b30 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f s.** less than o
29b40 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 r equal to zero
29b50 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 or if a memory a
29b60 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 llocate error oc
29b70 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 curs..**.** ^(Th
29b80 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 e amount of spac
29b90 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 e allocated by s
29ba0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
29bb0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 _context(C,N) is
29bc0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 .** determined b
29bd0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 y the N paramete
29be0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 r on first succe
29bf0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 ssful call. Cha
29c00 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c nging the.** val
29c10 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 ue of N in subse
29c20 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
29c30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
29c40 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e context() within
29c50 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 .** the same agg
29c60 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
29c70 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f instance will no
29c80 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d t resize the mem
29c90 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
29ca0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 n.)^.**.** ^SQLi
29cb0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
29cc0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 frees the memor
29cd0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a y allocated by .
29ce0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
29cf0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 gate_context() w
29d00 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 hen the aggregat
29d10 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 e query conclude
29d20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
29d30 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 st parameter mus
29d40 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 t be a copy of t
29d50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
29d60 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e ontext | SQL fun
29d70 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 ction context] t
29d80 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 hat is the first
29d90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
29da0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 the xStep or xF
29db0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f inal callback ro
29dc0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 utine that imple
29dd0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 ments the aggreg
29de0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e ate.** function.
29df0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
29e00 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
29e10 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
29e20 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
29e30 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 .** the aggregat
29e40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
29e50 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f s running..*/.vo
29e60 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 id *sqlite3_aggr
29e70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 egate_context(sq
29e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29e90 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a int nBytes);../*
29ea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 .** CAPI3REF: Us
29eb0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 er Data For Func
29ec0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tions.**.** ^The
29ed0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 sqlite3_user_da
29ee0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
29ef0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
29f00 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
29f10 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 that was the pUs
29f20 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 erData parameter
29f30 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 (the 5th parame
29f40 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ter).** of the [
29f50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
29f60 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e unction()].** an
29f70 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
29f80 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 e_function16()]
29f90 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 routines that or
29fa0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 iginally.** regi
29fb0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 stered the appli
29fc0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
29fd0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
29fe0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
29ff0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
2a000 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
2a010 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
2a020 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2a030 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
2a040 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 running..*/.void
2a050 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
2a060 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
2a070 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
2a080 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
2a090 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
2a0a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
2a0b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^The sqlite3_con
2a0c0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
2a0d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2a0e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
2a0f0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 the pointer to t
2a100 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2a110 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 nection] (the 1s
2a120 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
2a130 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
2a140 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2a150 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
2a160 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2a170 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
2a180 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
2a190 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
2a1a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
2a1b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
2a1c0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c .*/.sqlite3 *sql
2a1d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2a1e0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 handle(sqlite3_c
2a1f0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
2a200 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 CAPI3REF: Funct
2a210 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 ion Auxiliary Da
2a220 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c ta.**.** The fol
2a230 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 lowing two funct
2a240 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
2a250 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 by scalar SQL f
2a260 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 unctions to.** a
2a270 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 ssociate metadat
2a280 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 a with argument
2a290 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 values. If the s
2a2a0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 ame value is pas
2a2b0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 sed to.** multip
2a2c0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f le invocations o
2a2d0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 f the same SQL f
2a2e0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 unction during q
2a2f0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 uery execution,
2a300 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 under.** some ci
2a310 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 rcumstances the
2a320 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 associated metad
2a330 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 ata may be prese
2a340 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a rved. This may.*
2a350 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 * be used, for e
2a360 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 xample, to add a
2a370 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
2a380 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 ion matching sca
2a390 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e lar.** function.
2a3a0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 The compiled ve
2a3b0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 rsion of the reg
2a3c0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
2a3d0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 is stored as.**
2a3e0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
2a3f0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c ted with the SQL
2a400 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
2a410 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
2a420 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 ression.** patte
2a430 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 rn. The compile
2a440 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 d regular expres
2a450 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 sion can be reus
2a460 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a ed on multiple.*
2a470 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
2a480 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2a490 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f on so that the o
2a4a0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 riginal pattern
2a4b0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e string.** does n
2a4c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 ot need to be re
2a4d0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 compiled on each
2a4e0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a invocation..**.
2a4f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2a500 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
2a510 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2a520 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2a530 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
2a540 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 ociated by the s
2a550 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2a560 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 ta() function wi
2a570 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d th the Nth argum
2a580 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 ent.** value to
2a590 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2a5a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2a5b0 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 . ^If no metadat
2a5c0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a a has been ever.
2a5d0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 ** been set for
2a5e0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
2a5f0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
2a600 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 , or if the corr
2a610 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e esponding.** fun
2a620 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
2a630 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 has changed sinc
2a640 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 e the meta-data
2a650 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e was set,.** then
2a660 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
2a670 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 data() returns a
2a680 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
2a690 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2a6a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
2a6b0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 interface saves
2a6c0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 the metadata.**
2a6d0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 pointed to by it
2a6e0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 s 3rd parameter
2a6f0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 as the metadata
2a700 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 for the N-th.**
2a710 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
2a720 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2a730 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 ned function. S
2a740 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c ubsequent.** cal
2a750 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 ls to sqlite3_ge
2a760 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 t_auxdata() migh
2a770 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 t return this da
2a780 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a ta, if it has.**
2a790 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f not been destro
2a7a0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 yed..** ^If it i
2a7b0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 s not NULL, SQLi
2a7c0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2a7d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
2a7e0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 function given
2a7f0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d by the 4th param
2a800 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2a810 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e set_auxdata() on
2a820 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 .** the metadata
2a830 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 when the corres
2a840 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e ponding function
2a850 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
2a860 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 es.** or when th
2a870 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2a880 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 completes, which
2a890 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
2a8a0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
2a8b0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 s free to call t
2a8c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e he destructor an
2a8d0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 d drop metadata
2a8e0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 on any.** parame
2a8f0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 ter of any funct
2a900 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e ion at any time.
2a910 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 ^The only guar
2a920 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a antee is that.**
2a930 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
2a940 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 will be called b
2a950 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 efore the metada
2a960 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a ta is dropped..*
2a970 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 *.** ^(In practi
2a980 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 ce, metadata is
2a990 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 preserved betwee
2a9a0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 n function calls
2a9b0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 for.** expressi
2a9c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ons that are con
2a9d0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 stant at compile
2a9e0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c time. This incl
2a9f0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 udes literal.**
2aa00 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 values and [para
2aa10 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a meters].)^.**.**
2aa20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2aa30 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
2aa40 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
2aa50 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
2aa60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2aa70 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
2aa80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
2aa90 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
2aaa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
2aab0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 N);.void sqlite3
2aac0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
2aad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2aae0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
2aaf0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
2ab00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ab10 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
2ab20 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
2ab30 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a ructor Behavior.
2ab40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
2ab50 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
2ab60 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
2ab70 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
2ab80 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
2ab90 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
2aba0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
2abb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
2abc0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 ob()]. ^If the
2abd0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 destructor.** ar
2abe0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 gument is SQLITE
2abf0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e _STATIC, it mean
2ac00 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
2ac10 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f nt pointer is co
2ac20 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 nstant.** and wi
2ac30 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e ll never change.
2ac40 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 It does not ne
2ac50 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 ed to be destroy
2ac60 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c ed. ^The.** SQL
2ac70 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 ITE_TRANSIENT va
2ac80 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 lue means that t
2ac90 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 he content will
2aca0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e likely change in
2acb0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 .** the near fut
2acc0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c ure and that SQL
2acd0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 ite should make
2ace0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
2acf0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
2ad00 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 ontent before re
2ad10 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 turning..**.** T
2ad20 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 he typedef is ne
2ad30 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 cessary to work
2ad40 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 around problems
2ad50 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b in certain.** C+
2ad60 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 + compilers. Se
2ad70 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a e ticket #2191..
2ad80 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 */.typedef void
2ad90 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 (*sqlite3_destru
2ada0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a ctor_type)(void*
2adb0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 );.#define SQLIT
2adc0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 E_STATIC ((
2add0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
2ade0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 or_type)0).#defi
2adf0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ne SQLITE_TRANSI
2ae00 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f ENT ((sqlite3_
2ae10 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
2ae20 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 -1)../*.** CAPI3
2ae30 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 REF: Setting The
2ae40 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 Result Of An SQ
2ae50 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a L Function.**.**
2ae60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2ae70 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
2ae80 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
2ae90 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
2aea0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
2aeb0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
2aec0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
2aed0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
2aee0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
2aef0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
2af00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
2af10 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
2af20 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
2af30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
2af40 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
2af50 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
2af60 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
2af70 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
2af80 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
2af90 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
2afa0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
2afb0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
2afc0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
2afd0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
2afe0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
2aff0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
2b000 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
2b010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b020 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
2b030 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
2b040 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
2b050 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
2b060 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2b070 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
2b080 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
2b090 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
2b0a0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
2b0b0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
2b0c0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
2b0d0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
2b0e0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
2b0f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
2b100 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2b110 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 _zeroblob() inte
2b120 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 rfaces set the r
2b130 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
2b140 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2b150 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
2b160 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 be a BLOB contai
2b170 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a ning all zero.**
2b180 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 bytes and N byt
2b190 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 es in size, wher
2b1a0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 e N is the value
2b1b0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 of the 2nd para
2b1c0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
2b1d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2b1e0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 _double() interf
2b1f0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
2b200 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
2b210 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2b220 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
2b230 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 e a floating poi
2b240 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 nt value specifi
2b250 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 ed.** by its 2nd
2b260 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
2b270 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
2b280 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
2b290 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2b2a0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
2b2b0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
2b2c0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
2b2d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
2b2e0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
2b2f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
2b300 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e the string poin
2b310 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a ted to by the.**
2b320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
2b330 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 f sqlite3_result
2b340 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 _error() or sqli
2b350 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2b360 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 16().** as the t
2b370 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ext of an error
2b380 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 message. ^SQLit
2b390 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 e interprets the
2b3a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2b3b0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
2b3c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
2b3d0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e or() as UTF-8. ^
2b3e0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 SQLite.** interp
2b3f0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 rets the string
2b400 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
2b410 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 ult_error16() as
2b420 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
2b430 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e e.** byte order.
2b440 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 ^If the third
2b450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2b460 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2b470 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
2b480 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
2b490 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 () is negative t
2b4a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
2b4b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a as the error.**
2b4c0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 message all tex
2b4d0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 t up through the
2b4e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
2b4f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
2b500 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2b510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
2b520 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a ult_error() or.*
2b530 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
2b540 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f _error16() is no
2b550 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 n-negative then
2b560 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 SQLite takes tha
2b570 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 t many.** bytes
2b580 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
2b590 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
2b5a0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 rameter as the e
2b5b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
2b5c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
2b5d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
2b5e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2b5f0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 error16().** rou
2b600 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 tines make a pri
2b610 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
2b620 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
2b630 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ext before.** th
2b640 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 ey return. Henc
2b650 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 e, the calling f
2b660 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c unction can deal
2b670 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 locate or.** mod
2b680 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 ify the text aft
2b690 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 er they return w
2b6a0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
2b6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
2b6c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 ult_error_code()
2b6d0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 function change
2b6e0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
2b6f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
2b700 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 SQLite as a resu
2b710 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 lt of an error i
2b720 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e n a function. ^
2b730 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 By default,.** t
2b740 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 he error code is
2b750 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 SQLITE_ERROR.
2b760 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ^A subsequent ca
2b770 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 ll to sqlite3_re
2b780 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
2b790 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
2b7a0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 t_error16() rese
2b7b0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ts the error cod
2b7c0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f e to SQLITE_ERRO
2b7d0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 R..**.** ^The sq
2b7e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f lite3_result_too
2b7f0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 big() interface
2b800 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
2b810 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
2b820 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
2b830 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 at a string or B
2b840 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 LOB is too long
2b850 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
2b860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b870 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
2b880 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
2b890 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
2b8a0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
2b8b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
2b8c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2b8d0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e failed..**.** ^
2b8e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2b8f0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 lt_int() interfa
2b900 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
2b910 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
2b920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2b930 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
2b940 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 to be the 32-bit
2b950 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2b960 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
2b970 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
2b980 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 nt..** ^The sqli
2b990 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
2b9a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
2b9b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
2b9c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
2b9d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2b9e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2b9f0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 the 64-bit signe
2ba00 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
2ba10 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
2ba20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
2ba30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ba40 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 _result_null() i
2ba50 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
2ba60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
2ba70 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
2ba80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2ba90 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c ction to be NULL
2baa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2bab0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2bac0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 (), sqlite3_resu
2bad0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 lt_text16(),.**
2bae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2baf0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 ext16le(), and s
2bb00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2bb10 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 xt16be() interfa
2bb20 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 ces.** set the r
2bb30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
2bb40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2bb50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
2bb60 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 to be.** a text
2bb70 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 string which is
2bb80 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 represented as U
2bb90 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 TF-8, UTF-16 nat
2bba0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a ive byte order,.
2bbb0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 ** UTF-16 little
2bbc0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d endian, or UTF-
2bbd0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 16 big endian, r
2bbe0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2bbf0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 ^SQLite takes th
2bc00 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 e text result fr
2bc10 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 om the applicati
2bc20 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 on from.** the 2
2bc30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
2bc40 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
2bc50 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
2bc60 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ces..** ^If the
2bc70 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
2bc80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
2bc90 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
2bca0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 aces.** is negat
2bcb0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ive, then SQLite
2bcc0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 takes result te
2bcd0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 xt from the 2nd
2bce0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 parameter.** thr
2bcf0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
2bd00 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
2bd10 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 * ^If the 3rd pa
2bd20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
2bd30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2bd40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
2bd50 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 * is non-negativ
2bd60 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 e, then as many
2bd70 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
2bd80 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 cters) of the te
2bd90 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f xt.** pointed to
2bda0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
2bdb0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 meter are taken
2bdc0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 as the applicati
2bdd0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 on-defined.** fu
2bde0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a nction result..*
2bdf0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
2be00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
2be10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2be20 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
2be30 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
2be40 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f ult_blob is a no
2be50 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
2be60 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c then SQLite call
2be70 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 s that.** functi
2be80 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 on as the destru
2be90 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 ctor on the text
2bea0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
2beb0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 when it has.** f
2bec0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
2bed0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
2bee0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
2bef0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
2bf00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
2bf10 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f interfaces or to
2bf20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
2bf30 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
2bf40 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
2bf50 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 SQLITE_STATIC, t
2bf60 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 hen SQLite.** as
2bf70 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 sumes that the t
2bf80 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
2bf90 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e lt is in constan
2bfa0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 t space and does
2bfb0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 not.** copy the
2bfc0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2bfd0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 parameter nor ca
2bfe0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ll a destructor
2bff0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a on the content.*
2c000 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 * when it has fi
2c010 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
2c020 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
2c030 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
2c040 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
2c050 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
2c060 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
2c070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
2c080 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
2c090 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
2c0a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 TE_TRANSIENT.**
2c0b0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 then SQLite make
2c0c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
2c0d0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 result into spac
2c0e0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a e obtained from.
2c0f0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
2c100 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 _malloc()] befor
2c110 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a e it returns..**
2c120 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2c130 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
2c140 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
2c150 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
2c160 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2c170 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2c180 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
2c190 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
2c1a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2c1b0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
2c1c0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
2c1d0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a ameter. ^The.**
2c1e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2c1f0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
2c200 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
2c210 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
2c220 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 alue].** so that
2c230 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
2c240 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 lue] specified i
2c250 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 n the parameter
2c260 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a may change or.**
2c270 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
2c280 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 after sqlite3_re
2c290 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 sult_value() ret
2c2a0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 urns without har
2c2b0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 m..** ^A [protec
2c2c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2c2d0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c e] object may al
2c2e0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 ways be used whe
2c2f0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 re an.** [unprot
2c300 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2c310 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 lue] object is r
2c320 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 equired, so eith
2c330 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 er.** kind of [s
2c340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2c350 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 ject can be used
2c360 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 with this inter
2c370 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 face..**.** If t
2c380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
2c390 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 e called from wi
2c3a0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 thin the differe
2c3b0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 nt thread.** tha
2c3c0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 n the one contai
2c3d0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 ning the applica
2c3e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2c3f0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 ction that recei
2c400 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ved.** the [sqli
2c410 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 te3_context] poi
2c420 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 nter, the result
2c430 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2c440 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
2c450 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c _result_blob(sql
2c460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
2c470 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
2c480 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2c490 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
2c4a0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c esult_double(sql
2c4b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 ite3_context*, d
2c4c0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c ouble);.void sql
2c4d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2c4e0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
2c4f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
2c500 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
2c510 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2c520 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
2c530 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
2c540 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
2c550 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2c560 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 r_toobig(sqlite3
2c570 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
2c580 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2c590 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 error_nomem(sqli
2c5a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
2c5b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2c5c0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 lt_error_code(sq
2c5d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2c5e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
2c5f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 e3_result_int(sq
2c600 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2c610 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
2c620 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
2c630 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2c640 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
2c650 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
2c660 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 esult_null(sqlit
2c670 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
2c680 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2c690 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 t_text(sqlite3_c
2c6a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
2c6b0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 har*, int, void(
2c6c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
2c6d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2c6e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 text16(sqlite3_c
2c6f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
2c700 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
2c710 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
2c720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2c730 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
2c740 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
2c750 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
2c760 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
2c770 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2c780 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
2c790 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
2c7a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
2c7b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
2c7c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2c7d0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f t_value(sqlite3_
2c7e0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
2c7f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 3_value*);.void
2c800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
2c810 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
2c820 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 context*, int n)
2c830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c840 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f F: Define New Co
2c850 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 llating Sequence
2c860 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 s.**.** ^These f
2c870 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 unctions add, re
2c880 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 move, or modify
2c890 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 a [collation] as
2c8a0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
2c8b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2c8c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
2c8d0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
2c8e0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
2c8f0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
2c900 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 he collation is
2c910 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a a UTF-8 string.*
2c920 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
2c930 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
2c940 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 and sqlite3_cre
2c950 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
2c960 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d ().** and a UTF-
2c970 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
2c980 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 ive byte order f
2c990 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
2c9a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
2c9b0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e .** ^Collation n
2c9c0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 ames that compar
2c9d0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e e equal accordin
2c9e0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 g to [sqlite3_st
2c9f0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a rnicmp()] are.**
2ca00 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
2ca10 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e e the same name.
2ca20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 .**.** ^(The thi
2ca30 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 rd argument (eTe
2ca40 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f xtRep) must be o
2ca50 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 ne of the consta
2ca60 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 nts:.** <ul>.**
2ca70 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
2ca80 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8],.** <li> [SQL
2ca90 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a ITE_UTF16LE],.**
2caa0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
2cab0 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 F16BE],.** <li>
2cac0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
2cad0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
2cae0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
2caf0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a ]..** </ul>)^.**
2cb00 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 ^The eTextRep a
2cb10 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e rgument determin
2cb20 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 es the encoding
2cb30 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 of strings passe
2cb40 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c d.** to the coll
2cb50 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
2cb60 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 allback, xCallba
2cb70 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c ck..** ^The [SQL
2cb80 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b ITE_UTF16] and [
2cb90 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
2cba0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 GNED] values for
2cbb0 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 eTextRep.** for
2cbc0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 ce strings to be
2cbd0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 UTF16 with nati
2cbe0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
2cbf0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
2cc00 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
2cc10 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 lue for eTextRep
2cc20 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 forces strings
2cc30 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 to begin.** on a
2cc40 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 n even byte addr
2cc50 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ess..**.** ^The
2cc60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
2cc70 20 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c pArg, is a appl
2cc80 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
2cc90 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
2cca0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
2ccb0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
2ccc0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
2ccd0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
2cce0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
2ccf0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
2cd00 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
2cd10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2cd20 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
2cd30 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
2cd40 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
2cd50 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
2cd60 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
2cd70 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
2cd80 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
2cd90 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
2cda0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
2cdb0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
2cdc0 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
2cdd0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
2cde0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
2cdf0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
2ce00 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
2ce10 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
2ce20 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
2ce30 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
2ce40 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
2ce50 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
2ce60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
2ce70 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
2ce80 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
2ce90 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
2cea0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
2ceb0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
2cec0 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
2ced0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
2cee0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
2cef0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
2cf00 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
2cf10 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
2cf20 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
2cf30 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
2cf40 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
2cf50 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
2cf60 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
2cf70 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
2cf80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
2cf90 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
2cfa0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
2cfb0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
2cfc0 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
2cfd0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
2cfe0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
2cff0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
2d000 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
2d010 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
2d020 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
2d030 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
2d040 61 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ay return the sa
2d050 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 me answer.** giv
2d060 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 en the same inpu
2d070 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d ts. If two or m
2d080 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ore collating fu
2d090 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 nctions are regi
2d0a0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 stered.** to the
2d0b0 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 same collation
2d0c0 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 name (using diff
2d0d0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 erent eTextRep v
2d0e0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a alues) then all.
2d0f0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 ** must give an
2d100 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 equivalent answe
2d110 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 r when invoked w
2d120 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 ith equivalent s
2d130 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 trings..** The c
2d140 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2d150 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 n must obey the
2d160 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 following proper
2d170 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 ties for all.**
2d180 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e strings A, B, an
2d190 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a d C:.**.** <ol>.
2d1a0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 ** <li> If A==B
2d1b0 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c then B==A..** <l
2d1c0 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 i> If A==B and B
2d1d0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a ==C then A==C..*
2d1e0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
2d1f0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a THEN B>A..**
2d200 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 <li> If A<B
2d210 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 and B<C then
2d220 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e A<C..** </ol>
2d230 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c .**.** If a coll
2d240 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 ating function f
2d250 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 ails any of the
2d260 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 above constraint
2d270 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f s and that.** co
2d280 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
2d290 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 is registered
2d2a0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 and used, then t
2d2b0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 he behavior of S
2d2c0 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 QLite.** is unde
2d2d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2d2e0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
2d2f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
2d300 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
2d310 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2d320 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 ion().** with th
2d330 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 e addition that
2d340 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c the xDestroy cal
2d350 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
2d360 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a on pArg when.**
2d370 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
2d380 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
2d390 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e ed..** ^Collatin
2d3a0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 g functions are
2d3b0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 deleted when the
2d3c0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
2d3d0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c by later.** cal
2d3e0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 ls to the collat
2d3f0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e ion creation fun
2d400 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 ctions or when t
2d410 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
2d420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 connection] is c
2d430 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c losed using [sql
2d440 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
2d450 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 *.** ^The xDestr
2d460 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c oy callback is <
2d470 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 u>not</u> called
2d480 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 if the .** sqli
2d490 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2d4a0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 tion_v2() functi
2d4b0 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 on fails. Appli
2d4c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 cations that inv
2d4d0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 oke.** sqlite3_c
2d4e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
2d4f0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d v2() with a non-
2d500 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 NULL xDestroy ar
2d510 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a gument should .*
2d520 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 * check the retu
2d530 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 rn code and disp
2d540 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ose of the appli
2d550 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
2d560 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 ter.** themselve
2d570 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 s rather than ex
2d580 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 pecting SQLite t
2d590 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 o deal with it f
2d5a0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 or them..** This
2d5b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 is different fr
2d5c0 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 om every other S
2d5d0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
2d5e0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 The inconsiste
2d5f0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 ncy .** is unfor
2d600 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f tunate but canno
2d610 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 t be changed wit
2d620 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 hout breaking ba
2d630 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 ckwards .** comp
2d640 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
2d650 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c See also: [sql
2d660 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2d670 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 eeded()] and [sq
2d680 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2d690 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a needed16()]..*/.
2d6a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
2d6b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 te_collation(.
2d6c0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
2d6d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
2d6e0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2d6f0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a . void *pArg,.
2d700 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
2d710 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
2d720 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
2d730 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 void*).);.int s
2d740 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2d750 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 llation_v2(. sq
2d760 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2d770 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
2d780 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
2d790 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 void *pArg,.
2d7a0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
2d7b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
2d7c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
2d7d0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 oid*),. void(*x
2d7e0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
2d7f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2d800 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
2d810 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
2d820 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e const void *zN
2d830 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 ame,. int eText
2d840 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 Rep, . void *pA
2d850 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 rg,. int(*xComp
2d860 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
2d870 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
2d880 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
2d890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d8a0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 Collation Needed
2d8b0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
2d8c0 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e ^To avoid havin
2d8d0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
2d8e0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
2d8f0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
2d900 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
2d910 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
2d920 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2d930 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
2d940 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
2d950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2d960 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 ction] to be inv
2d970 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
2d980 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
2d990 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
2d9a0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
2d9b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 .** ^If the func
2d9c0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 tion is register
2d9d0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c ed using the sql
2d9e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2d9f0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 eeded() API,.**
2da00 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 then it is passe
2da10 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 d the names of u
2da20 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
2da30 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 on sequences as
2da40 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 strings.** encod
2da50 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 ed in UTF-8. ^If
2da60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2da70 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 on_needed16() is
2da80 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 used,.** the na
2da90 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 mes are passed a
2daa0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 s UTF-16 in mach
2dab0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 ine native byte
2dac0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c order..** ^A cal
2dad0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 l to either func
2dae0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 tion replaces th
2daf0 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 e existing colla
2db00 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c tion-needed call
2db10 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 back..**.** ^(Wh
2db20 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
2db30 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 is invoked, the
2db40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 first argument p
2db50 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a assed is a copy.
2db60 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ** of the second
2db70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
2db80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2db90 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 eeded() or.** sq
2dba0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2dbb0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 needed16(). The
2dbc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2dbd0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
2dbe0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
2dbf0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
2dc00 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 ent is one of [S
2dc10 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 QLITE_UTF8], [SQ
2dc20 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a LITE_UTF16BE],.*
2dc30 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 * or [SQLITE_UTF
2dc40 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 16LE], indicatin
2dc50 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 g the most desir
2dc60 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 able form of the
2dc70 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
2dc80 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 quence function
2dc90 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 required. The f
2dca0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2dcb0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
2dcc0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 he.** required c
2dcd0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2dce0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 e.)^.**.** The c
2dcf0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2dd00 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 should register
2dd10 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
2dd20 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 lation using.**
2dd30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2dd40 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 collation()], [s
2dd50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2dd60 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 llation16()], or
2dd70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
2dd80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
2dd90 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
2dda0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2ddb0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a eded(. sqlite3*
2ddc0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 , . void*, . v
2ddd0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
2dde0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
2ddf0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a ep,const char*).
2de00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2de10 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
2de20 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
2de30 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 void*,. void(
2de40 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2de50 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
2de60 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
2de70 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 #ifdef SQLITE_HA
2de80 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 S_CODEC./*.** Sp
2de90 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f ecify the key fo
2dea0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 r an encrypted d
2deb0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 atabase. This r
2dec0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 outine should be
2ded0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 .** called right
2dee0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f after sqlite3_o
2def0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 pen()..**.** The
2df00 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 code to impleme
2df10 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e nt this API is n
2df20 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ot available in
2df30 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 the public relea
2df40 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e se.** of SQLite.
2df50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2df60 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
2df70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2df80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2df90 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
2dfa0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2dfb0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
2dfc0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a /* The key *
2dfd0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e /.);../*.** Chan
2dfe0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e ge the key on an
2dff0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 open database.
2e000 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 If the current
2e010 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a database is not.
2e020 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 ** encrypted, th
2e030 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
2e040 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 encrypt it. If
2e050 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d pNew==0 or nNew=
2e060 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 =0, the.** datab
2e070 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 ase is decrypted
2e080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
2e090 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
2e0a0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
2e0b0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
2e0c0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
2e0d0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
2e0e0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 nt sqlite3_rekey
2e0f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2e100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e110 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 /* Database t
2e120 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a o be rekeyed */.
2e130 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b const void *pK
2e140 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 ey, int nKey
2e150 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 /* The new key
2e160 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 */.);../*.** 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 53 45 ion key for a SE
2e190 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c E database. Unl
2e1a0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
2e1b0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 d, none of the S
2e1c0 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c EE routines will
2e1d0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 work..*/.void s
2e1e0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f qlite3_activate_
2e1f0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 see(. const cha
2e200 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
2e210 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
2e220 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
2e230 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
2e240 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 SQLITE_ENABLE_CE
2e250 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 ROD./*.** Specif
2e260 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e y the activation
2e270 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 key for a CEROD
2e280 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
2e290 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
2e2a0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 , none of the CE
2e2b0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c ROD routines wil
2e2c0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
2e2d0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
2e2e0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
2e2f0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
2e300 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
2e310 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
2e320 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
2e330 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
2e340 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
2e350 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
2e360 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2e370 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
2e380 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
2e390 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
2e3a0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
2e3b0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
2e3c0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
2e3d0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
2e3e0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
2e3f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
2e400 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
2e410 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
2e420 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
2e430 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
2e440 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
2e450 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
2e460 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
2e470 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
2e480 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
2e490 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
2e4a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
2e4b0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
2e4c0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
2e4d0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
2e4e0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
2e4f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
2e500 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
2e510 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
2e520 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
2e530 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
2e540 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
2e550 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
2e560 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
2e570 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
2e580 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
2e590 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
2e5a0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
2e5b0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
2e5c0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
2e5d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
2e5e0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
2e5f0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
2e600 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
2e610 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
2e620 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
2e630 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
2e640 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 3_sleep(int);../
2e650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2e660 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 ame Of The Folde
2e670 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 r Holding Tempor
2e680 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 ary Files.**.**
2e690 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c ^(If this global
2e6a0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 variable is mad
2e6b0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 e to point to a
2e6c0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a string which is.
2e6d0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
2e6e0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 folder (a.k.a.
2e6f0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
2e700 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
2e710 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
2e720 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 by SQLite when u
2e730 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
2e740 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
2e750 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 FS].** will be p
2e760 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
2e770 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 rectory.)^ ^If
2e780 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
2e790 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2e7a0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
2e7b0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
2e7c0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
2e7d0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
2e7e0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
2e7f0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
2e800 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
2e810 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
2e820 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
2e830 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
2e840 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
2e850 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
2e860 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
2e870 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
2e880 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
2e890 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
2e8a0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
2e8b0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
2e8c0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
2e8d0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
2e8e0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
2e8f0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
2e900 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
2e910 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
2e920 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
2e930 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
2e940 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
2e950 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
2e960 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
2e970 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
2e980 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
2e990 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
2e9a0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 ** ^The [temp_st
2e9b0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2e9c0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
2e9d0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
2e9e0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
2e9f0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
2ea00 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
2ea10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
2ea20 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
2ea30 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 .** the [temp_st
2ea40 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2ea50 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
2ea60 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
2ea70 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
2ea80 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
2ea90 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
2eaa0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2eab0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
2eac0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
2ead0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
2eae0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
2eaf0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
2eb00 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
2eb10 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
2eb20 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
2eb30 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
2eb40 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
2eb50 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
2eb60 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
2eb70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
2eb80 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2eb90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
2eba0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
2ebb0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 of the [temp_st
2ebc0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
2ebd0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
2ebe0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
2ebf0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
2ec00 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
2ec10 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
2ec20 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
2ec30 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
2ec40 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 de.** KEYWORDS:
2ec50 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 {autocommit mode
2ec60 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c }.**.** ^The sql
2ec70 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
2ec80 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 mit() interface
2ec90 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2eca0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 or.** zero if t
2ecb0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 he given databas
2ecc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2ecd0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
2ece0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a ocommit mode,.**
2ecf0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 respectively.
2ed00 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 ^Autocommit mode
2ed10 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
2ed20 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
2ed30 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c t mode is disabl
2ed40 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 ed by a [BEGIN]
2ed50 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 statement..** ^A
2ed60 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
2ed70 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 s re-enabled by
2ed80 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 a [COMMIT] or [R
2ed90 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 OLLBACK]..**.**
2eda0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 If certain kinds
2edb0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 of errors occur
2edc0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 on a statement
2edd0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 within a multi-s
2ede0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e tatement.** tran
2edf0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 saction (errors
2ee00 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 including [SQLIT
2ee10 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_FULL], [SQLITE
2ee20 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c _IOERR],.** [SQL
2ee30 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
2ee40 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b ITE_BUSY], and [
2ee50 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
2ee60 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 ]) then the.** t
2ee70 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 ransaction might
2ee80 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
2ee90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
2eea0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a The only way to.
2eeb0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 ** find out whet
2eec0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d her SQLite autom
2eed0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2eee0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
2eef0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e tion after.** an
2ef00 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 error is to use
2ef10 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a this function..
2ef20 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
2ef30 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
2ef40 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
2ef50 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
2ef60 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
2ef70 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
2ef80 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
2ef90 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
2efa0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
2efb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
2efc0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
2efd0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
2efe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2eff0 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
2f000 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
2f010 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2f020 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ment.**.** ^The
2f030 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
2f040 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 e interface retu
2f050 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 rns the [databas
2f060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
2f070 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 ndle.** to which
2f080 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2f090 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
2f0a0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 ^The [database
2f0b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
2f0c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2f0d0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
2f0e0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
2f0f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
2f100 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 ** that was the
2f110 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
2f120 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2f130 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2f140 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 call (or its var
2f150 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 iants) that was
2f160 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 used to.** creat
2f170 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
2f180 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
2f190 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a ce..*/.sqlite3 *
2f1a0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
2f1b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 e(sqlite3_stmt*)
2f1c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f1d0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 F: Find the next
2f1e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2f1f0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ent.**.** ^This
2f200 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2f210 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2f220 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
2f230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
2f240 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
2f250 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2f260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2f270 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 tion] pDb. ^If
2f280 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a pStmt is NULL.**
2f290 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 then this inter
2f2a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2f2b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 ointer to the fi
2f2c0 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 rst prepared sta
2f2d0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 tement.** associ
2f2e0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 ated with the da
2f2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f300 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 n pDb. ^If no p
2f310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f320 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 t.** satisfies t
2f330 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 he conditions of
2f340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 this routine, i
2f350 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a t returns NULL..
2f360 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 **.** The [datab
2f370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2f380 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 pointer D in a c
2f390 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
2f3a0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
2f3b0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
2f3c0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
2f3d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
2f3e0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 and in particula
2f3f0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 r must not be a
2f400 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
2f410 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 .sqlite3_stmt *s
2f420 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
2f430 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 (sqlite3 *pDb, s
2f440 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2f450 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2f460 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 3REF: Commit And
2f470 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 Rollback Notifi
2f480 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
2f490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f4a0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2f4b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2f4c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2f4d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2f4e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2f4f0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2f500 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 n is [COMMIT | c
2f510 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 ommitted]..** ^A
2f520 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
2f530 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
2f540 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
2f550 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
2f560 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2f570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2f580 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2f590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
2f5a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 ollback_hook() i
2f5b0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
2f5c0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
2f5d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2f5e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
2f5f0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2f600 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f s [ROLLBACK | ro
2f610 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e lled back]..** ^
2f620 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 Any callback set
2f630 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 by a previous c
2f640 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
2f650 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a ollback_hook().*
2f660 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2f670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f680 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2f690 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 ..** ^The pArg a
2f6a0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
2f6b0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
2f6c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 callback..** ^I
2f6d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f f the callback o
2f6e0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 n a commit hook
2f6f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
2f700 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 non-zero,.** th
2f710 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 en the commit is
2f720 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 converted into
2f730 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a a rollback..**.*
2f740 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2f750 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 ommit_hook(D,C,P
2f760 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f ) and sqlite3_ro
2f770 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c llback_hook(D,C,
2f780 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 P) functions.**
2f790 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 return the P arg
2f7a0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 ument from the p
2f7b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 revious call of
2f7c0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2f7d0 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 n.** on the same
2f7e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2f7f0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c ction] D, or NUL
2f800 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 L for.** the fir
2f810 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 st call for each
2f820 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a function on D..
2f830 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
2f840 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ck implementatio
2f850 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
2f860 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
2f870 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
2f880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2f890 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
2f8a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 the callback. A
2f8b0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
2f8c0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2f8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2f8e0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
2f8f0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
2f900 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
2f910 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
2f920 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
2f930 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 triggered the c
2f940 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c ommit.** or roll
2f950 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 back hook in the
2f960 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
2f970 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
2f980 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2f990 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
2f9a0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
2f9b0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
2f9c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
2f9d0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
2f9e0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
2f9f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
2fa00 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 **.** ^Registeri
2fa10 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 ng a NULL functi
2fa20 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 on disables the
2fa30 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
2fa40 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 ^When the commit
2fa50 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 hook callback r
2fa60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
2fa70 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 ero, the [COMMIT
2fa80 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 ].** operation i
2fa90 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e s allowed to con
2faa0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 tinue normally.
2fab0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 ^If the commit
2fac0 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 hook.** returns
2fad0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
2fae0 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 he [COMMIT] is c
2faf0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
2fb00 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e [ROLLBACK]..** ^
2fb10 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f The rollback hoo
2fb20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 k is invoked on
2fb30 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 a rollback that
2fb40 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 results from a c
2fb50 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 ommit.** hook re
2fb60 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f turning non-zero
2fb70 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 , just as it wou
2fb80 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f ld be with any o
2fb90 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ther rollback..*
2fba0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
2fbb0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 rposes of this A
2fbc0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f PI, a transactio
2fbd0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 n is said to hav
2fbe0 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 e been.** rolled
2fbf0 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c back if an expl
2fc00 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 icit "ROLLBACK"
2fc10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 statement is exe
2fc20 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 cuted, or.** an
2fc30 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 error or constra
2fc40 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d int causes an im
2fc50 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 plicit rollback
2fc60 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 to occur..** ^Th
2fc70 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
2fc80 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
2fc90 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
2fca0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
2fcb0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
2fcc0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
2fcd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2fce0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
2fcf0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
2fd00 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 e [sqlite3_updat
2fd10 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 e_hook()] interf
2fd20 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ace..*/.void *sq
2fd30 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
2fd40 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 k(sqlite3*, int(
2fd50 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
2fd60 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
2fd70 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 _rollback_hook(s
2fd80 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 qlite3*, void(*)
2fd90 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 (void *), void*)
2fda0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2fdb0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e F: Data Change N
2fdc0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c otification Call
2fdd0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 backs.**.** ^The
2fde0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f sqlite3_update_
2fdf0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
2fe00 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
2fe10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
2fe20 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
2fe30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2fe40 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
2fe50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2fe60 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b t.** to be invok
2fe70 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f ed whenever a ro
2fe80 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
2fe90 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
2fea0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 d..** ^Any callb
2feb0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
2fec0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
2fed0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 is function.** f
2fee0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2fef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2ff00 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2ff10 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
2ff20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2ff30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 ointer to the fu
2ff40 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 nction to invoke
2ff50 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 when a.** row i
2ff60 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
2ff70 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
2ff80 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
2ff90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 gument to the ca
2ffa0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
2ffb0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 of the third ar
2ffc0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
2ffd0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2ffe0 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f ()..** ^The seco
2fff0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
30000 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
30010 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
30020 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
30030 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
30040 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
30050 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
30060 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
30070 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
30080 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
30090 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 ^The third and
300a0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
300b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
300c0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
300d0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
300e0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e base and table n
300f0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ame containing t
30100 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e he affected row.
30110 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 .** ^The final c
30120 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
30130 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
30140 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
30150 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 ^In the case of
30160 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 an update, this
30170 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 is the [rowid] a
30180 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 fter the update
30190 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a takes place..**.
301a0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 ** ^(The update
301b0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f hook is not invo
301c0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
301d0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 l system tables
301e0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 are.** modified
301f0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 (i.e. sqlite_mas
30200 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 ter and sqlite_s
30210 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a equence).)^.**.*
30220 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e * ^In the curren
30230 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
30240 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f , the update hoo
30250 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f k.** is not invo
30260 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 ked when duplica
30270 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 tion rows are de
30280 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 leted because of
30290 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c an.** [ON CONFL
302a0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 ICT | ON CONFLIC
302b0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 T REPLACE] claus
302c0 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 e. ^Nor is the
302d0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
302e0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 nvoked when rows
302f0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 are deleted usi
30300 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 ng the [truncate
30310 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a optimization]..
30320 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e ** The exception
30330 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 s defined in thi
30340 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 s paragraph migh
30350 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 t change in a fu
30360 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
30370 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
30380 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
30390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
303a0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
303b0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
303c0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
303d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
303e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
303f0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 e update hook.
30400 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
30410 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
30420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30430 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
30440 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
30450 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
30460 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
30470 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
30480 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
30490 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 update hook..**
304a0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
304b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
304c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
304d0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
304e0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
304f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
30500 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
30510 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
30520 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
30530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30540 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
30550 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a C,P) function.**
30560 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 returns the P a
30570 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
30580 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a previous call.*
30590 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
305a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
305b0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
305c0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
305d0 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a call on D..**.**
305e0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
305f0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
30600 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ok()] and [sqlit
30610 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
30620 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
30630 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 s..*/.void *sqli
30640 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
30650 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
30660 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 void(*)(void *,i
30670 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a nt ,char const *
30680 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 ,char const *,sq
30690 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 lite3_int64),.
306a0 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*.);../*.**
306b0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
306c0 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 Or Disable Shar
306d0 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a ed Pager Cache.*
306e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 * KEYWORDS: {sha
306f0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a red cache}.**.**
30700 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
30710 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
30720 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 les the sharing
30730 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
30740 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 cache.** and sch
30750 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 ema data structu
30760 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 res between [dat
30770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30780 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a | connections].
30790 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 ** to the same d
307a0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 atabase. Sharing
307b0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
307c0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 he argument is t
307d0 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 rue.** and disab
307e0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
307f0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a ent is false.)^.
30800 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 **.** ^Cache sha
30810 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 ring is enabled
30820 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 and disabled for
30830 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 an entire proce
30840 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 ss..** This is a
30850 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 change as of SQ
30860 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
30870 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 .0. In prior ver
30880 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c sions of SQLite,
30890 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 .** sharing was
308a0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
308b0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 led for each thr
308c0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ead separately..
308d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 **.** ^(The cach
308e0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 e sharing mode s
308f0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 et by this inter
30900 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c face effects all
30910 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 subsequent.** c
30920 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
30930 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
30940 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 e3_open_v2()], a
30950 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
30960 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 16()]..** Existi
30970 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ng database conn
30980 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 ections continue
30990 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 use the sharing
309a0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 mode.** that wa
309b0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 s in effect at t
309c0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 he time they wer
309d0 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a e opened.)^.**.*
309e0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
309f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
30a00 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
30a10 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
30a20 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
30a30 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
30a40 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
30a50 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
30a60 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 wise.)^.**.** ^S
30a70 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
30a80 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
30a90 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
30aa0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
30ab0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
30ac0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
30ad0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
30ae0 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
30af0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
30b00 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
30b10 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
30b20 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
30b30 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
30b40 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 Mode].*/.int sq
30b50 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
30b60 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a red_cache(int);.
30b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30b80 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 Attempt To Free
30b90 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a Heap Memory.**.
30ba0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
30bb0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
30bc0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
30bd0 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 pts to free N by
30be0 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d tes.** of heap m
30bf0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 emory by dealloc
30c00 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 ating non-essent
30c10 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ial memory alloc
30c20 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 ations.** held b
30c30 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c y the database l
30c40 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 ibrary. Memory
30c50 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 used to cache d
30c60 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 atabase.** pages
30c70 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 to improve perf
30c80 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 ormance is an ex
30c90 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 ample of non-ess
30ca0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a ential memory..*
30cb0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * ^sqlite3_relea
30cc0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 se_memory() retu
30cd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
30ce0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 f bytes actually
30cf0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 freed,.** which
30d00 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
30d10 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 r less than the
30d20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
30d30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
30d40 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
30d50 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
30d60 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 no-op returning
30d70 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 zero.** if SQLit
30d80 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 e is not compile
30d90 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 d with [SQLITE_E
30da0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e NABLE_MEMORY_MAN
30db0 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 AGEMENT]..*/.int
30dc0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
30dd0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f _memory(int);../
30de0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
30df0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e mpose A Limit On
30e00 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a Heap Size.**.**
30e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f ^The sqlite3_so
30e20 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
30e30 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
30e40 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 and/or queries
30e50 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 the.** soft limi
30e60 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 t on the amount
30e70 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 of heap memory t
30e80 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 hat may be alloc
30e90 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a ated by SQLite..
30ea0 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 ** ^SQLite striv
30eb0 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 es to keep heap
30ec0 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 memory utilizati
30ed0 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 on below the sof
30ee0 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 t heap.** limit
30ef0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 by reducing the
30f00 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
30f10 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 held in the page
30f20 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 cache.** as hea
30f30 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 p memory usages
30f40 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c approaches the l
30f50 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f imit..** ^The so
30f60 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
30f70 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 "soft" because
30f80 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 even though SQLi
30f90 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 te strives to st
30fa0 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 ay.** below the
30fb0 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 limit, it will e
30fc0 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 xceed the limit
30fd0 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 rather than gene
30fe0 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 rate.** an [SQLI
30ff0 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e TE_NOMEM] error.
31000 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
31010 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
31020 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 limit .** is adv
31030 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a isory only..**.*
31040 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 * ^The return va
31050 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
31060 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
31070 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 64() is the size
31080 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 of.** the soft
31090 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 heap limit prior
310a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e to the call. ^
310b0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 If the argument
310c0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a N is negative.**
310d0 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 then no change
310e0 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 is made to the s
310f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 oft heap limit.
31100 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 Hence, the curr
31110 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 ent.** size of t
31120 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
31130 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d it can be determ
31140 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 ined by invoking
31150 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 .** sqlite3_soft
31160 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 _heap_limit64()
31170 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 with a negative
31180 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
31190 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 ^If the argument
311a0 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 N is zero then
311b0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
311c0 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e mit is disabled.
311d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 .**.** ^(The sof
311e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
311f0 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 not enforced in
31200 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c the current impl
31210 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 ementation.** if
31220 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
31230 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 following condit
31240 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a ions are true:.*
31250 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
31260 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 > The soft heap
31270 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 limit is set to
31280 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 zero..** <li> Me
31290 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 mory accounting
312a0 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e is disabled usin
312b0 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 g a combination
312c0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b of the.** [
312d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
312e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
312f0 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 EMSTATUS],...) s
31300 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e tart-time option
31310 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 and.** the
31320 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
31330 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 _MEMSTATUS] comp
31340 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
31350 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 .** <li> An alte
31360 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 rnative page cac
31370 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
31380 6e 20 69 73 20 73 70 65 63 69 66 65 64 20 75 73 n is specifed us
31390 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c ing.** [sql
313a0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
313b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
313c0 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 HE],...)..** <li
313d0 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65 > The page cache
313e0 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 allocates from
313f0 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 its own memory p
31400 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ool supplied.**
31410 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 by [sqlite3
31420 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
31430 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
31440 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 E],...) rather t
31450 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d han.** from
31460 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f the heap..** </
31470 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 ul>)^.**.** Begi
31480 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 nning with SQLit
31490 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c e version 3.7.3,
314a0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
314b0 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 imit is enforced
314c0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f .** regardless o
314d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
314e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 the [SQLITE_ENA
314f0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 BLE_MEMORY_MANAG
31500 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c EMENT].** compil
31510 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
31520 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 invoked. With
31530 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
31540 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 EMORY_MANAGEMENT
31550 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 ],.** the soft h
31560 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 eap limit is enf
31570 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d orced on every m
31580 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
31590 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 . Without.** [S
315a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
315b0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c ORY_MANAGEMENT],
315c0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
315d0 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 imit is only enf
315e0 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 orced.** when me
315f0 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 mory is allocate
31600 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 d by the page ca
31610 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 che. Testing su
31620 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61 ggests that beca
31630 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 use.** the page
31640 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65 cache is the pre
31650 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 dominate memory
31660 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 user in SQLite,
31670 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
31680 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 ions will achiev
31690 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 e adequate soft
316a0 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 heap limit enfor
316b0 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a cement without.*
316c0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 * the use of [SQ
316d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f LITE_ENABLE_MEMO
316e0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a RY_MANAGEMENT]..
316f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d **.** The circum
31700 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 stances under wh
31710 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ich SQLite will
31720 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 enforce the soft
31730 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a heap limit may.
31740 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 ** changes in fu
31750 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
31760 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 SQLite..*/.sqli
31770 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
31780 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
31790 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 t64(sqlite3_int6
317a0 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4 N);../*.** CAP
317b0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
317c0 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 d Soft Heap Limi
317d0 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 t Interface.** D
317e0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
317f0 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63 This is a deprec
31800 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 ated version of
31810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 the [sqlite3_sof
31820 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
31830 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 ].** interface.
31840 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
31850 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 provided for hi
31860 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
31870 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 bility.** only.
31880 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 All new applica
31890 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 tions should use
318a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
318b0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
318c0 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64()] interface
318d0 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 rather than this
318e0 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f one..*/.SQLITE_
318f0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
31900 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
31910 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a p_limit(int N);.
31920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31930 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 : Extract Metada
31940 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
31950 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a n Of A Table.**.
31960 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
31970 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 returns metadat
31980 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 a about a specif
31990 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 ic column of a s
319a0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 pecific.** datab
319b0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 ase table access
319c0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b ible using the [
319d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
319e0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 ion] handle.** p
319f0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
31a00 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 st function argu
31a10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
31a20 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 column is ident
31a30 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
31a40 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 ond, third and f
31a50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
31a60 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to.** this func
31a70 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e tion. ^The secon
31a80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 d parameter is e
31a90 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f ither the name o
31aa0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
31ab0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 * (i.e. "main",
31ac0 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 "temp", or an at
31ad0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 tached database)
31ae0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
31af0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 specified.** tab
31b00 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 le or NULL. ^If
31b10 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e it is NULL, then
31b20 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 all attached da
31b30 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 tabases are sear
31b40 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ched.** for the
31b50 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 table using the
31b60 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 same algorithm u
31b70 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 sed by the datab
31b80 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a ase engine to.**
31b90 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 resolve unquali
31ba0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 fied table refer
31bb0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ences..**.** ^Th
31bc0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
31bd0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
31be0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 this function a
31bf0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 re the table and
31c00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 column.** name
31c10 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 of the desired c
31c20 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 olumn, respectiv
31c30 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 ely. Neither of
31c40 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
31c50 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e .** may be NULL.
31c60 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 .**.** ^Metadata
31c70 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 is returned by
31c80 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d writing to the m
31c90 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 emory locations
31ca0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 passed as the 5t
31cb0 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 h.** and subsequ
31cc0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ent parameters t
31cd0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e o this function.
31ce0 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 ^Any of these a
31cf0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a rguments may be.
31d00 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 ** NULL, in whic
31d10 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 h case the corre
31d20 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 sponding element
31d30 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 of metadata is
31d40 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e omitted..**.** ^
31d50 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a (<blockquote>.**
31d60 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
31d70 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
31d80 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f Parameter <th> O
31d90 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 utput<br>Type <t
31da0 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a h> Description.
31db0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 **.** <tr><td> 5
31dc0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 th <td> const ch
31dd0 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 ar* <td> Data ty
31de0 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 pe.** <tr><td> 6
31df0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 th <td> const ch
31e00 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 ar* <td> Name of
31e10 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 default collati
31e20 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c on sequence.** <
31e30 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e tr><td> 7th <td>
31e40 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
31e50 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
31e60 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 has a NOT NULL
31e70 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 constraint.** <t
31e80 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 r><td> 8th <td>
31e90 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e int <td>
31ea0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
31eb0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 is part of the P
31ec0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 RIMARY KEY.** <t
31ed0 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 r><td> 9th <td>
31ee0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e int <td>
31ef0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
31f00 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e is [AUTOINCREMEN
31f10 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a T].** </table>.*
31f20 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 * </blockquote>)
31f30 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ^.**.** ^The mem
31f40 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ory pointed to b
31f50 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 y the character
31f60 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
31f70 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 d for the.** dec
31f80 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e laration type an
31f90 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
31fa0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e ence is valid on
31fb0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 ly until the nex
31fc0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 t.** call to any
31fd0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 SQLite API func
31fe0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tion..**.** ^If
31ff0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 the specified ta
32000 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 ble is actually
32010 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f a view, an [erro
32020 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
32030 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ned..**.** ^If t
32040 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c he specified col
32050 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 umn is "rowid",
32060 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 "oid" or "_rowid
32070 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e _" and an.** [IN
32080 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
32090 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 Y] column has be
320a0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 en explicitly de
320b0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 clared, then the
320c0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
320d0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f eters are set fo
320e0 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 r the explicitly
320f0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
32100 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 . ^(If there is
32110 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 no.** explicitly
32120 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 declared [INTEG
32130 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
32140 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 column, then the
32150 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
32160 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 eters are set as
32170 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
32180 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 <pre>.** dat
32190 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 a type: "INTEGER
321a0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 ".** collati
321b0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 on sequence: "BI
321c0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 NARY".** not
321d0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 null: 0.**
321e0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a primary key: 1.*
321f0 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 * auto incre
32200 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 ment: 0.** </pre
32210 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 >)^.**.** ^(This
32220 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f function may lo
32230 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 ad one or more s
32240 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 chemas from data
32250 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 base files. If a
32260 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 n.** error occur
32270 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 s during this pr
32280 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 ocess, or if the
32290 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 requested table
322a0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 or column.** ca
322b0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 nnot be found, a
322c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
322d0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
322e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
322f0 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b left.** in the [
32300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32310 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 ion] (to be retr
32320 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 ieved using sqli
32330 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e te3_errmsg()).)^
32340 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 .**.** ^This API
32350 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
32360 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
32370 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
32380 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
32390 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
323a0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
323b0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
323c0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 defined..*/.int
323d0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 sqlite3_table_c
323e0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a olumn_metadata(.
323f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
32400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
32410 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 Connection hand
32420 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
32430 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 ar *zDbName,
32440 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
32450 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a name or NULL */.
32460 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 const char *zT
32470 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a ableName, /*
32480 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 Table name */.
32490 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f const char *zCo
324a0 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 lumnName, /*
324b0 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 Column name */.
324c0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
324d0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 DataType, /*
324e0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 OUTPUT: Declared
324f0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 data type */.
32500 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 char const **pzC
32510 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f ollSeq, /* O
32520 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e UTPUT: Collation
32530 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a sequence name *
32540 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c /. int *pNotNul
32550 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 l,
32560 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
32570 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 if NOT NULL cons
32580 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f traint exists */
32590 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 . int *pPrimary
325a0 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f Key, /
325b0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
325c0 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 f column part of
325d0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 PK */. int *pA
325e0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 utoinc
325f0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
32600 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 True if column i
32610 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 s auto-increment
32620 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
32630 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 PI3REF: Load An
32640 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Extension.**.**
32650 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 ^This interface
32660 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 loads an SQLite
32670 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 extension librar
32680 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 y from the named
32690 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 file..**.** ^Th
326a0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
326b0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
326c0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
326d0 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 load an.** SQLi
326e0 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 te extension lib
326f0 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 rary contained i
32700 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 n the file zFile
32710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 ..**.** ^The ent
32720 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f ry point is zPro
32730 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 c..** ^zProc may
32740 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 be 0, in which
32750 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 case the name of
32760 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 the entry point
32770 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 .** defaults to
32780 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 "sqlite3_extensi
32790 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 on_init"..** ^Th
327a0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
327b0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
327c0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
327d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
327e0 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 uccess and [SQLI
327f0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d TE_ERROR] if som
32800 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ething goes wron
32810 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 g..** ^If an err
32820 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a or occurs and pz
32830 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c ErrMsg is not 0,
32840 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 then the.** [sq
32850 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
32860 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 sion()] interfac
32870 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 e shall attempt
32880 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 to.** fill *pzEr
32890 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 rMsg with error
328a0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f message text sto
328b0 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a red in memory.**
328c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
328d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
328e0 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 ]. The calling f
328f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c unction.** shoul
32900 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f d free this memo
32910 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ry by calling [s
32920 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
32930 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e **.** ^Extension
32940 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 loading must be
32950 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a enabled using.*
32960 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c * [sqlite3_enabl
32970 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e e_load_extension
32980 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c ()] prior to cal
32990 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a ling this API,.*
329a0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 * otherwise an e
329b0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 rror will be ret
329c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 urned..**.** See
329d0 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f also the [load_
329e0 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 extension() SQL
329f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e function]..*/.in
32a00 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 t sqlite3_load_e
32a10 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 xtension(. sqli
32a20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
32a30 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 /* Load the ex
32a40 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 tension into thi
32a50 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 s database conne
32a60 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 ction */. const
32a70 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 char *zFile,
32a80 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 /* Name of the
32a90 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 shared library c
32aa0 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 ontaining extens
32ab0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ion */. const c
32ac0 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f har *zProc, /
32ad0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 * Entry point.
32ae0 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 Derived from zFi
32af0 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 le if 0 */. cha
32b00 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 r **pzErrMsg
32b10 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 /* Put error
32b20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 message here if
32b30 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a not 0 */.);../*.
32b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
32b50 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
32b60 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 xtension Loading
32b70 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f .**.** ^So as no
32b80 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 t to open securi
32b90 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 ty holes in olde
32ba0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 r applications t
32bb0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 hat are.** unpre
32bc0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 pared to deal wi
32bd0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 th extension loa
32be0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d ding, and as a m
32bf0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e eans of disablin
32c00 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c g.** extension l
32c10 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 oading while eva
32c20 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 luating user-ent
32c30 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f ered SQL, the fo
32c40 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 llowing API.** i
32c50 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 s provided to tu
32c60 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rn the [sqlite3_
32c70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
32c80 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 ] mechanism on a
32c90 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 nd off..**.** ^E
32ca0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
32cb0 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 is off by defau
32cc0 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 lt. See ticket #
32cd0 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 1863..** ^Call t
32ce0 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c he sqlite3_enabl
32cf0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e e_load_extension
32d00 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 () routine with
32d10 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 onoff==1.** to t
32d20 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f urn extension lo
32d30 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c ading on and cal
32d40 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d l it with onoff=
32d50 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 =0 to turn.** it
32d60 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e back off again.
32d70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
32d80 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
32d90 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 nsion(sqlite3 *d
32da0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a b, int onoff);..
32db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32dc0 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f Automatically Lo
32dd0 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 ad Statically Li
32de0 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a nked Extensions.
32df0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
32e00 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 rface causes the
32e10 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 xEntryPoint() f
32e20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
32e30 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 voked for.** eac
32e40 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 h new [database
32e50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
32e60 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 is created. Th
32e70 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 74 e idea here is t
32e80 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 hat.** xEntryPoi
32e90 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 nt() is the entr
32ea0 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 y point for a st
32eb0 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 atically linked
32ec0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e SQLite extension
32ed0 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 .** that is to b
32ee0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
32ef0 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 loaded into all
32f00 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
32f10 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 nections..**.**
32f20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 ^(Even though th
32f30 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f e function proto
32f40 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 type shows that
32f50 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 xEntryPoint() ta
32f60 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 kes.** no argume
32f70 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 nts and returns
32f80 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 void, SQLite inv
32f90 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 okes xEntryPoint
32fa0 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a () with three.**
32fb0 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 arguments and e
32fc0 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 xpects and integ
32fd0 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 er result as if
32fe0 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 the signature of
32ff0 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f the.** entry po
33000 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c int where as fol
33010 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
33020 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
33030 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e int xEn
33040 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 tryPoint(.** &nb
33050 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a sp; sqlite3 *
33060 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 db,.**
33070 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
33080 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 ErrMsg,.**  
33090 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 ; const struc
330a0 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f t sqlite3_api_ro
330b0 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a utines *pThunk.*
330c0 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 * );.**
330d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
330e0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 te>)^.**.** If t
330f0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 he xEntryPoint r
33100 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 outine encounter
33110 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 s an error, it s
33120 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 hould make *pzEr
33130 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f rMsg.** point to
33140 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
33150 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f error message (o
33160 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
33170 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
33180 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 ).** and return
33190 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
331a0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 error code]. ^S
331b0 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 QLite ensures th
331c0 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 at *pzErrMsg.**
331d0 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 is NULL before c
331e0 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 alling the xEntr
331f0 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 yPoint(). ^SQLi
33200 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a te will invoke.*
33210 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
33220 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 )] on *pzErrMsg
33230 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e after xEntryPoin
33240 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 t() returns. ^I
33250 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 f any.** xEntryP
33260 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 oint() returns a
33270 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 n error, the [sq
33280 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
33290 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
332a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
332b0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 3_open_v2()] cal
332c0 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 l that provoked
332d0 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 the xEntryPoint(
332e0 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a ) will fail..**.
332f0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
33300 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 te3_auto_extensi
33310 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e on(X) with an en
33320 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 try point X that
33330 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f is already.** o
33340 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 n the list of au
33350 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
33360 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 ns is a harmless
33370 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 no-op. ^No entr
33380 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 y point.** will
33390 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 be called more t
333a0 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 han once for eac
333b0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
333c0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 ction that is op
333d0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ened..**.** See
333e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 also: [sqlite3_r
333f0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
33400 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 ion()]..*/.int s
33410 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
33420 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e nsion(void (*xEn
33430 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 tryPoint)(void))
33440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33450 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 F: Reset Automat
33460 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 ic Extension Loa
33470 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ding.**.** ^This
33480 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61 62 interface disab
33490 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 les all automati
334a0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 c extensions pre
334b0 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 viously.** regis
334c0 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c tered using [sql
334d0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 ite3_auto_extens
334e0 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 ion()]..*/.void
334f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 sqlite3_reset_au
33500 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 to_extension(voi
33510 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 d);../*.** The i
33520 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
33530 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
33540 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
33550 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
33560 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
33570 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
33580 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
33590 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
335a0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
335b0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
335c0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
335d0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
335e0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
335f0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
33600 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
33610 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
33620 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
33630 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
33640 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
33650 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
33660 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
33670 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f this comment..*/
33680 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 ../*.** Structur
33690 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 es used by the v
336a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
336b0 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 erface.*/.typede
336c0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
336d0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 _vtab sqlite3_vt
336e0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 ab;.typedef stru
336f0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
33700 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e _info sqlite3_in
33710 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 dex_info;.typede
33720 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
33730 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c _vtab_cursor sql
33740 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
33750 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
33760 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
33770 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a sqlite3_module;.
33780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33790 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f Virtual Table O
337a0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
337b0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
337c0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e {virtual table
337d0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 module}.**.** T
337e0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 his structure, s
337f0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 ometimes called
33800 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 a a "virtual tab
33810 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
33820 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
33830 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
33840 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
33850 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
33860 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
33870 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
33880 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
33890 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 .**.** ^A virtua
338a0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 l table module i
338b0 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c s created by fil
338c0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 ling in a persis
338d0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 tent.** instance
338e0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 of this structu
338f0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 re and passing a
33900 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
33910 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 instance.** to
33920 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33930 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 module()] or [sq
33940 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
33950 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 ule_v2()]..** ^T
33960 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 he registration
33970 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e remains valid un
33980 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 til it is replac
33990 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e ed by a differen
339a0 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 t.** module or u
339b0 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 ntil the [databa
339c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
339d0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 loses. The cont
339e0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 ent.** of this s
339f0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f tructure must no
33a00 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 t change while i
33a10 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 t is registered
33a20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 with.** any data
33a30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
33a40 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
33a50 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
33a60 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
33a70 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
33a80 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
33a90 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
33aa0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
33ab0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
33ac0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
33ad0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
33ae0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
33af0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
33b00 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
33b10 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
33b20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
33b30 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
33b40 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
33b50 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
33b60 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
33b70 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
33b80 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
33b90 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
33ba0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
33bb0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
33bc0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
33bd0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
33be0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
33bf0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
33c00 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
33c10 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
33c20 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
33c30 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
33c40 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
33c50 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
33c60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
33c70 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
33c80 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
33c90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
33ca0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
33cb0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
33cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
33cd0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
33ce0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
33cf0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
33d00 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
33d10 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
33d20 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
33d30 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
33d40 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
33d50 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
33d60 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
33d70 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
33d80 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
33d90 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
33da0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
33db0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
33dc0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
33dd0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
33de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
33df0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
33e00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
33e10 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
33e20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
33e30 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
33e40 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
33e50 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
33e60 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
33e70 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
33e80 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
33e90 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
33ea0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
33eb0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
33ec0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
33ed0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
33ee0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
33ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
33f00 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
33f10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33f20 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33f30 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
33f40 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
33f50 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 **ppArg);. int
33f60 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
33f70 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
33f80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
33f90 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 w);.};../*.** CA
33fa0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
33fb0 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 Table Indexing I
33fc0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 nformation.** KE
33fd0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
33fe0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a index_info.**.**
33ff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 The sqlite3_ind
34000 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
34010 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 e and its substr
34020 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 uctures is used
34030 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 as part.** of th
34040 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e [virtual table
34050 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
34060 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 * pass informati
34070 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 on into and rece
34080 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 ive the reply fr
34090 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 om the [xBestInd
340a0 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 ex].** method of
340b0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
340c0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 e module]. The
340d0 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 fields under **I
340e0 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a nputs** are the.
340f0 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 ** inputs to xBe
34100 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 stIndex and are
34110 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 read-only. xBes
34120 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 tIndex inserts i
34130 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ts.** results in
34140 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 to the **Outputs
34150 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a ** fields..**.**
34160 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 ^(The aConstrai
34170 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 nt[] array recor
34180 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ds WHERE clause
34190 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 constraints of t
341a0 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c he form:.**.** <
341b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d blockquote>colum
341c0 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b n OP expr</block
341d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 quote>.**.** whe
341e0 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b re OP is =, <
341f0 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f , <=, >, o
34200 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 r >=.)^ ^(Th
34210 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 e particular ope
34220 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 rator is.** stor
34230 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e ed in aConstrain
34240 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 t[].op using one
34250 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 of the.** [SQLI
34260 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
34270 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f INT_EQ | SQLITE_
34280 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
34290 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 _ values].)^.**
342a0 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 ^(The index of t
342b0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f he column is sto
342c0 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 red in.** aConst
342d0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e raint[].iColumn.
342e0 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e )^ ^(aConstrain
342f0 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 t[].usable is TR
34300 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 UE if the.** exp
34310 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 r on the right-h
34320 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 and side can be
34330 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 evaluated (and t
34340 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 hus the constrai
34350 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 nt.** is usable)
34360 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 and false if it
34370 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a cannot.)^.**.**
34380 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 ^The optimizer
34390 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
343a0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 verts terms of t
343b0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 he form "expr OP
343c0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 column".** and
343d0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 makes other simp
343e0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 lifications to t
343f0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
34400 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
34410 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 .** get as many
34420 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 WHERE clause ter
34430 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d ms into the form
34440 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 shown above as
34450 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 possible..** ^Th
34460 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 e aConstraint[]
34470 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 array only repor
34480 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ts WHERE clause
34490 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a terms that are.*
344a0 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 * relevant to th
344b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 e particular vir
344c0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 tual table being
344d0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 queried..**.**
344e0 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f ^Information abo
344f0 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 ut the ORDER BY
34500 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 clause is stored
34510 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a in aOrderBy[]..
34520 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 ** ^Each term of
34530 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 aOrderBy record
34540 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 s a column of th
34550 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
34560 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 e..**.** The [xB
34570 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 estIndex] method
34580 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 must fill aCons
34590 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 traintUsage[] wi
345a0 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a th information.*
345b0 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 * about what par
345c0 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 ameters to pass
345d0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 to xFilter. ^If
345e0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 argvIndex>0 the
345f0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 n.** the right-h
34600 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 and side of the
34610 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 corresponding aC
34620 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 onstraint[] is e
34630 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 valuated.** and
34640 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 becomes the argv
34650 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 Index-th entry i
34660 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 n argv. ^(If aC
34670 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
34680 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 .omit.** is true
34690 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 , then the const
346a0 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 raint is assumed
346b0 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e to be fully han
346c0 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 dled by the.** v
346d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 irtual table and
346e0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 is not checked
346f0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e again by SQLite.
34700 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 )^.**.** ^The id
34710 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 xNum and idxPtr
34720 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 values are recor
34730 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 ded and passed i
34740 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c nto the.** [xFil
34750 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 ter] method..**
34760 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 ^[sqlite3_free()
34770 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 ] is used to fre
34780 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 e idxPtr if and
34790 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 only if.** needT
347a0 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 oFreeIdxPtr is t
347b0 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rue..**.** ^The
347c0 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 orderByConsumed
347d0 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 means that outpu
347e0 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d t from [xFilter]
347f0 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 /[xNext] will oc
34800 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f cur in.** the co
34810 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 rrect order to s
34820 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 atisfy the ORDER
34830 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 BY clause so th
34840 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a at no separate.*
34850 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 * sorting step i
34860 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a s required..**.*
34870 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 * ^The estimated
34880 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e Cost value is an
34890 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 estimate of the
348a0 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 cost of doing t
348b0 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 he.** particular
348c0 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c lookup. A full
348d0 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 scan of a table
348e0 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 with N entries
348f0 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 should have.** a
34900 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 cost of N. A b
34910 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 inary search of
34920 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 a table of N ent
34930 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
34940 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 a.** cost of ap
34950 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 proximately log(
34960 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 N)..*/.struct sq
34970 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
34980 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a {. /* Inputs *
34990 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 /. int nConstra
349a0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f int; /
349b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 * Number of entr
349c0 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 ies in aConstrai
349d0 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 nt */. struct s
349e0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
349f0 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 straint {. i
34a00 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 nt iColumn;
34a10 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 /* Colu
34a20 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 mn on left-hand
34a30 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 side of constrai
34a40 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 nt */. unsig
34a50 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 ned char op;
34a60 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 /* Constrai
34a70 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 nt operator */.
34a80 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
34a90 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a r usable; /*
34aa0 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f True if this co
34ab0 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 nstraint is usab
34ac0 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 le */. int i
34ad0 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 TermOffset;
34ae0 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 /* Used int
34af0 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 ernally - xBestI
34b00 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f ndex should igno
34b10 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 re */. } *aCons
34b20 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 traint;
34b30 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 /* Table of W
34b40 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 HERE clause cons
34b50 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 traints */. int
34b60 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 nOrderBy;
34b70 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
34b80 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 r of terms in th
34b90 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
34ba0 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 e */. struct sq
34bb0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 lite3_index_orde
34bc0 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 rby {. int i
34bd0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 Column;
34be0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e /* Column n
34bf0 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e umber */. un
34c00 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 signed char desc
34c10 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 ; /* True
34c20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 for DESC. False
34c30 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d for ASC. */. }
34c40 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 *aOrderBy;
34c50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 /* The
34c60 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
34c70 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 */. /* Outputs
34c80 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c */. struct sql
34c90 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 ite3_index_const
34ca0 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 raint_usage {.
34cb0 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b int argvIndex;
34cc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 /* if
34cd0 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 >0, constraint
34ce0 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 is part of argv
34cf0 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 to xFilter */.
34d00 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
34d10 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f omit; /* Do
34d20 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 not code a test
34d30 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 for this constr
34d40 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f aint */. } *aCo
34d50 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 nstraintUsage;.
34d60 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 int idxNum;
34d70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
34d80 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 umber used to id
34d90 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 entify the index
34da0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 */. char *idxS
34db0 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 tr;
34dc0 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 /* String, poss
34dd0 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 ibly obtained fr
34de0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
34df0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 c */. int needT
34e00 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 oFreeIdxStr;
34e10 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 /* Free idxStr
34e20 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 using sqlite3_f
34e30 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f ree() if true */
34e40 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f . int orderByCo
34e50 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a nsumed; /*
34e60 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 True if output
34e70 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 is already order
34e80 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 ed */. double e
34e90 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 stimatedCost;
34ea0 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 /* Estimated
34eb0 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 cost of using th
34ec0 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a is index */.};..
34ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34ee0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f Virtual Table Co
34ef0 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f nstraint Operato
34f00 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 r Codes.**.** Th
34f10 65 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e ese macros defin
34f20 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 ed the allowed v
34f30 61 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a alues for the.**
34f40 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f [sqlite3_index_
34f50 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e info].aConstrain
34f60 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 t[].op field. E
34f70 61 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 ach value repres
34f80 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 ents.** an opera
34f90 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74 tor that is part
34fa0 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 of a constraint
34fb0 20 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 term in the wHE
34fc0 52 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 RE clause of.**
34fd0 61 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65 a query that use
34fe0 73 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 s a [virtual tab
34ff0 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 le]..*/.#define
35000 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
35010 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a STRAINT_EQ 2.
35020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
35030 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
35040 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 GT 4.#define
35050 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
35060 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a STRAINT_LE 8.
35070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
35080 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
35090 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 LT 16.#define
350a0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
350b0 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 NSTRAINT_GE 3
350c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
350d0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
350e0 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a T_MATCH 64../*.*
350f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
35100 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 ster A Virtual T
35110 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 able Implementat
35120 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ion.**.** ^These
35130 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
35140 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ed to register a
35150 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 new [virtual ta
35160 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 ble module] name
35170 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d ..** ^Module nam
35180 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 es must be regis
35190 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 tered before.**
351a0 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b creating a new [
351b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 virtual table] u
351c0 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 sing the module
351d0 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 and before using
351e0 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e a.** preexistin
351f0 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 g [virtual table
35200 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 ] for the module
35210 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 ..**.** ^The mod
35220 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 ule name is regi
35230 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 stered on the [d
35240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
35250 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a on] specified.**
35260 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 by the first pa
35270 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e rameter. ^The n
35280 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
35290 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 e is given by th
352a0 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 e .** second par
352b0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 ameter. ^The th
352c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
352d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a a pointer to.**
352e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
352f0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 ion of the [virt
35300 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
35310 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 ]. ^The fourth
35320 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 .** parameter is
35330 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c an arbitrary cl
35340 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 ient data pointe
35350 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
35360 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f through.** into
35370 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 the [xCreate] a
35380 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 nd [xConnect] me
35390 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 thods of the vir
353a0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
353b0 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 e.** when a new
353c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 virtual table is
353d0 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 be being create
353e0 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a d or reinitializ
353f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
35400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
35410 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 dule_v2() interf
35420 61 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 ace has a fifth
35430 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
35440 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
35450 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 to a destructor
35460 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 for the pClientD
35470 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 ata. ^SQLite wi
35480 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 ll.** invoke the
35490 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
354a0 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e tion (if it is n
354b0 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 ot NULL) when SQ
354c0 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 Lite.** no longe
354d0 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 r needs the pCli
354e0 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e entData pointer.
354f0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
35500 72 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 r will also.** b
35510 65 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 e invoked if the
35520 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
35530 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
35540 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 2() fails..** ^T
35550 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
35560 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e e_module().** in
35570 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 terface is equiv
35580 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 alent to sqlite3
35590 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
355a0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2() with a NULL.
355b0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a ** destructor..*
355c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
355d0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 eate_module(. s
355e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
355f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
35600 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
35610 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
35620 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
35630 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
35640 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
35650 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
35660 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
35670 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
35680 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
35690 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
356a0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 *pClientData
356b0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
356c0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
356d0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b e/xConnect */.);
356e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
356f0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 ate_module_v2(.
35700 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
35710 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
35720 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e QLite connection
35730 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 to register mod
35740 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f ule with */. co
35750 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
35760 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 /* Name
35770 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a of the module *
35780 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 /. const sqlite
35790 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 3_module *p, /
357a0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 * Methods for th
357b0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f e module */. vo
357c0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c id *pClientData,
357d0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 /* Clie
357e0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 nt data for xCre
357f0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a ate/xConnect */.
35800 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
35810 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 )(void*) /*
35820 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f Module destructo
35830 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b r function */.);
35840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35850 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
35860 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a Instance Object.
35870 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
35880 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 ite3_vtab.**.**
35890 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 Every [virtual t
358a0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 able module] imp
358b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
358c0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f a subclass.** o
358d0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f f this object to
358e0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 describe a part
358f0 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a icular instance.
35900 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 ** of the [virtu
35910 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 al table]. Each
35920 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a subclass will.*
35930 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f * be tailored to
35940 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
35950 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c eds of the modul
35960 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
35970 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 ..** The purpose
35980 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c of this supercl
35990 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 ass is to define
359a0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 certain fields
359b0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d that are.** comm
359c0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 on to all module
359d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
359e0 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c ..**.** ^Virtual
359f0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 tables methods
35a00 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 can set an error
35a10 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 message by assi
35a20 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e gning a.** strin
35a30 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
35a40 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
35a50 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ()] to zErrMsg.
35a60 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 The method shou
35a70 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 ld.** take care
35a80 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 that any prior s
35a90 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 tring is freed b
35aa0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c y a call to [sql
35ab0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 ite3_free()].**
35ac0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 prior to assigni
35ad0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 ng a new string
35ae0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 to zErrMsg. ^Af
35af0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
35b00 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 ssage.** is deli
35b10 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 vered up to the
35b20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 client applicati
35b30 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 on, the string w
35b40 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
35b50 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 ally.** freed by
35b60 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
35b70 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 and the zErrMsg
35b80 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 field will be ze
35b90 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 roed..*/.struct
35ba0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 sqlite3_vtab {.
35bb0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
35bc0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 odule *pModule;
35bd0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 /* The module f
35be0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 or this virtual
35bf0 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e table */. int n
35c00 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 Ref;
35c10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f /* NO
35c20 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a LONGER USED */.
35c30 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b char *zErrMsg;
35c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35c50 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 /* Error messa
35c60 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ge from sqlite3_
35c70 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f mprintf() */. /
35c80 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * Virtual table
35c90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
35ca0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 will typically a
35cb0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 dd additional fi
35cc0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a elds */.};../*.*
35cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
35ce0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 ual Table Cursor
35cf0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
35d00 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 RDS: sqlite3_vta
35d10 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 b_cursor {virtua
35d20 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a l table cursor}.
35d30 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 **.** Every [vir
35d40 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
35d50 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f e] implementatio
35d60 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
35d70 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c s of the.** foll
35d80 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 owing structure
35d90 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
35da0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
35db0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 nto the.** [virt
35dc0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 ual table] and a
35dd0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f re used.** to lo
35de0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 op through the v
35df0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 irtual table. C
35e00 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 ursors are creat
35e10 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
35e20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e [sqlite3_module.
35e30 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d xOpen | xOpen] m
35e40 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 ethod of the mod
35e50 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 ule and are dest
35e60 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 royed.** by the
35e70 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e [sqlite3_module.
35e80 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d xClose | xClose]
35e90 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 method. Cursor
35ea0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 s are used.** by
35eb0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 the [xFilter],
35ec0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c [xNext], [xEof],
35ed0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 [xColumn], and
35ee0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 [xRowid] methods
35ef0 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c .** of the modul
35f00 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 e. Each module
35f10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
35f20 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 ill define.** th
35f30 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 e content of a c
35f40 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 ursor structure
35f50 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 to suit its own
35f60 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 needs..**.** Thi
35f70 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 s superclass exi
35f80 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 sts in order to
35f90 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 define fields of
35fa0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 the cursor that
35fb0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 .** are common t
35fc0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 o all implementa
35fd0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 tions..*/.struct
35fe0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
35ff0 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 rsor {. sqlite3
36000 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 _vtab *pVtab;
36010 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 /* Virtual ta
36020 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 ble of this curs
36030 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 or */. /* Virtu
36040 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
36050 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 ntations will ty
36060 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 pically add addi
36070 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f tional fields */
36080 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
36090 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 REF: Declare The
360a0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 Schema Of A Vir
360b0 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a tual Table.**.**
360c0 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 ^The [xCreate]
360d0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d and [xConnect] m
360e0 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b ethods of a.** [
360f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
36100 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 dule] call this
36110 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
36120 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d declare the form
36130 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e at (the names an
36140 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 d datatypes of t
36150 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a he columns) of.*
36160 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 * the virtual ta
36170 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d bles they implem
36180 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ent..*/.int sqli
36190 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 te3_declare_vtab
361a0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
361b0 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f char *zSQL);../
361c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
361d0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 verload A Functi
361e0 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c on For A Virtual
361f0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 Table.**.** ^(V
36200 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 irtual tables ca
36210 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e n provide altern
36220 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ative implementa
36230 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f tions of functio
36240 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 ns.** using the
36250 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 [xFindFunction]
36260 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 method of the [v
36270 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
36280 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 ule]. .** But g
36290 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f lobal versions o
362a0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e f those function
362b0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 s.** must exist
362c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f in order to be o
362d0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a verloaded.)^.**.
362e0 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 ** ^(This API ma
362f0 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 kes sure a globa
36300 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 l version of a f
36310 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 unction with a p
36320 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d articular.** nam
36330 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 e and number of
36340 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 parameters exist
36350 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 s. If no such f
36360 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a unction exists.*
36370 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 * before this AP
36380 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e I is called, a n
36390 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 ew function is c
363a0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 reated.)^ ^The
363b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
363c0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e * of the new fun
363d0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 ction always cau
363e0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e ses an exception
363f0 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 to be thrown.
36400 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 So.** the new fu
36410 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f nction is not go
36420 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 od for anything
36430 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 by itself. Its
36440 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 only.** purpose
36450 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 is to be a place
36460 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 holder function
36470 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 that can be over
36480 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b loaded.** by a [
36490 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a virtual table]..
364a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
364b0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e verload_function
364c0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
364d0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 char *zFuncName
364e0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a , int nArg);../*
364f0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
36500 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
36510 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
36520 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 defined above (
36530 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 back up.** to a
36540 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 comment remarkab
36550 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 ly similar to th
36560 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 is one) is curre
36570 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
36580 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
36590 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
365a0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
365b0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
365c0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
365d0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
365e0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
365f0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
36600 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
36610 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
36620 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
36630 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
36640 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
36650 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
36660 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
36670 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
36680 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
36690 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f this comment..*/
366a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
366b0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e : A Handle To An
366c0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 Open BLOB.** KE
366d0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 YWORDS: {BLOB ha
366e0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 ndle} {BLOB hand
366f0 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e les}.**.** An in
36700 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
36710 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
36720 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e an open BLOB on
36730 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 which.** [sqlit
36740 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
36750 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
36760 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 I/O] can be perf
36770 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 ormed..** ^Objec
36780 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 ts of this type
36790 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b are created by [
367a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
367b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 n()].** and dest
367c0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
367d0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
367e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
367f0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 3_blob_read()] a
36800 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
36810 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 _write()] interf
36820 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 aces.** can be u
36830 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 sed to read or w
36840 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 rite small subse
36850 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c ctions of the BL
36860 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c OB..** ^The [sql
36870 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
36880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
36890 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 urns the size of
368a0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 the BLOB in byt
368b0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 es..*/.typedef s
368c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c truct sqlite3_bl
368d0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b ob sqlite3_blob;
368e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
368f0 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f : Open A BLOB Fo
36900 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f r Incremental I/
36910 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 O.**.** ^(This i
36920 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 nterfaces opens
36930 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c a [BLOB handle |
36940 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 handle] to the
36950 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 BLOB located.**
36960 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c in row iRow, col
36970 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 umn zColumn, tab
36980 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 le zTable in dat
36990 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e abase zDb;.** in
369a0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
369b0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 e same BLOB that
369c0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 would be select
369d0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 ed by:.**.** <pr
369e0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 e>.** SELECT
369f0 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 zColumn FROM zD
36a00 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b b.zTable WHERE [
36a10 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a rowid] = iRow;.*
36a20 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a * </pre>)^.**.**
36a30 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 ^If the flags p
36a40 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d arameter is non-
36a50 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 zero, then the B
36a60 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f LOB is opened fo
36a70 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 r read.** and wr
36a80 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 ite access. ^If
36a90 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 it is zero, the
36aa0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
36ab0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a or read access..
36ac0 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f ** ^It is not po
36ad0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 ssible to open a
36ae0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 column that is
36af0 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 part of an index
36b00 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 or primary .**
36b10 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e key for writing.
36b20 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 ^If [foreign ke
36b30 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 y constraints] a
36b40 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 re enabled, it i
36b50 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 s .** not possib
36b60 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c le to open a col
36b70 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 umn that is part
36b80 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 of a [child key
36b90 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a ] for writing..*
36ba0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 *.** ^Note that
36bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
36bc0 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c e is not the fil
36bd0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 ename that conta
36be0 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ins.** the datab
36bf0 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 ase but rather t
36c00 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 he symbolic name
36c10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
36c20 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 that.** appears
36c30 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 after the AS ke
36c40 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 yword when the d
36c50 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 atabase is conne
36c60 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 cted using [ATTA
36c70 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 CH]..** ^For the
36c80 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
36c90 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 ile, the databas
36ca0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 e name is "main"
36cb0 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 ..** ^For TEMP t
36cc0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 ables, the datab
36cd0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d ase name is "tem
36ce0 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 p"..**.** ^(On s
36cf0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f uccess, [SQLITE_
36d00 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OK] is returned
36d10 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f and the new [BLO
36d20 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 B handle] is wri
36d30 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c tten.** to *ppBl
36d40 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e ob. Otherwise an
36d50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
36d60 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 returned and *p
36d70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 pBlob is set.**
36d80 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 to be a null poi
36d90 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 nter.)^.** ^This
36da0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 function sets t
36db0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
36dc0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 nection] error c
36dd0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a ode and message.
36de0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 ** accessible vi
36df0 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f a [sqlite3_errco
36e00 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 de()] and [sqlit
36e10 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
36e20 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 related.** func
36e30 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 tions. ^Note tha
36e40 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 t the *ppBlob va
36e50 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 riable is always
36e60 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 initialized in
36e70 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 a.** way that ma
36e80 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 kes it safe to i
36e90 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 nvoke [sqlite3_b
36ea0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 lob_close()] on
36eb0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 *ppBlob.** regar
36ec0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
36ed0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 cess or failure
36ee0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
36ef0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
36f00 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 row that a BLOB
36f10 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f handle points to
36f20 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 is modified by
36f30 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 an.** [UPDATE],
36f40 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 [DELETE], or by
36f50 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 [ON CONFLICT] si
36f60 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 de-effects.** th
36f70 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 en the BLOB hand
36f80 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 le is marked as
36f90 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 "expired"..** Th
36fa0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e is is true if an
36fb0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 y column of the
36fc0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 row is changed,
36fd0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a even a column.**
36fe0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 other than the
36ff0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e one the BLOB han
37000 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 dle is open on.)
37010 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b ^.** ^Calls to [
37020 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
37030 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
37040 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 3_blob_write()]
37050 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 for.** a expired
37060 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 BLOB handle fai
37070 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e l with an return
37080 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
37090 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 _ABORT]..** ^(Ch
370a0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e anges written in
370b0 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 to a BLOB prior
370c0 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 to the BLOB expi
370d0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ring are not.**
370e0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 rolled back by t
370f0 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 he expiration of
37100 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 the BLOB. Such
37110 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 changes will ev
37120 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d entually.** comm
37130 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 it if the transa
37140 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 ction continues
37150 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e to completion.)^
37160 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 .**.** ^Use the
37170 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
37180 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
37190 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 to determine th
371a0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 e size of.** the
371b0 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e opened blob. ^
371c0 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c The size of a bl
371d0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 ob may not be ch
371e0 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a anged by this.**
371f0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 interface. Use
37200 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 the [UPDATE] SQ
37210 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 L command to cha
37220 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 nge the size of
37230 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a a.** blob..**.**
37240 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 ^The [sqlite3_b
37250 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 ind_zeroblob()]
37260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 and [sqlite3_res
37270 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 ult_zeroblob()]
37280 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e interfaces.** an
37290 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b d the built-in [
372a0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 zeroblob] SQL fu
372b0 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 nction can be us
372c0 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a ed, if desired,.
372d0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 ** to create an
372e0 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c empty, zero-fill
372f0 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 ed blob in which
37300 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 to read or writ
37310 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 e using.** this
37320 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
37330 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f To avoid a reso
37340 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 urce leak, every
37350 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
37360 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 le] should event
37370 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 ually.** be rele
37380 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 ased by a call t
37390 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
373a0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 close()]..*/.int
373b0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 sqlite3_blob_op
373c0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a en(. sqlite3*,.
373d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
373e0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
373f0 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 *zTable,. const
37400 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a char *zColumn,.
37410 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 sqlite3_int64
37420 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 iRow,. int flag
37430 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f s,. sqlite3_blo
37440 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f b **ppBlob.);../
37450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
37460 6f 76 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c ove a BLOB Handl
37470 65 20 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a e to a New Row.*
37480 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
37490 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6d ion is used to m
374a0 6f 76 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 ove an existing
374b0 62 6c 6f 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 blob handle so t
374c0 68 61 74 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a hat it points.**
374d0 20 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20 to a different
374e0 72 6f 77 20 6f 66 20 74 68 65 20 73 61 6d 65 20 row of the same
374f0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
37500 5e 54 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20 ^The new row is
37510 69 64 65 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79 identified.** by
37520 20 74 68 65 20 72 6f 77 69 64 20 76 61 6c 75 65 the rowid value
37530 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
37540 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 econd argument.
37550 4f 6e 6c 79 20 74 68 65 20 72 6f 77 20 63 61 6e Only the row can
37560 20 62 65 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20 be.** changed.
37570 5e 54 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 ^The database, t
37580 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 able and column
37590 6f 6e 20 77 68 69 63 68 20 74 68 65 20 62 6c 6f on which the blo
375a0 62 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e b handle is open
375b0 0a 2a 2a 20 72 65 6d 61 69 6e 20 74 68 65 20 73 .** remain the s
375c0 61 6d 65 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65 ame. Moving an e
375d0 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e xisting blob han
375e0 64 6c 65 20 74 6f 20 61 20 6e 65 77 20 72 6f 77 dle to a new row
375f0 20 63 61 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65 can be.** faste
37600 72 20 74 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74 r than closing t
37610 68 65 20 65 78 69 73 74 69 6e 67 20 68 61 6e 64 he existing hand
37620 6c 65 20 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61 le and opening a
37630 20 6e 65 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 new one..**.**
37640 5e 28 54 68 65 20 6e 65 77 20 72 6f 77 20 6d 75 ^(The new row mu
37650 73 74 20 6d 65 65 74 20 74 68 65 20 73 61 6d 65 st meet the same
37660 20 63 72 69 74 65 72 69 61 20 61 73 20 66 6f 72 criteria as for
37670 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
37680 70 65 6e 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d pen()] -.** it m
37690 75 73 74 20 65 78 69 73 74 20 61 6e 64 20 74 68 ust exist and th
376a0 65 72 65 20 6d 75 73 74 20 62 65 20 65 69 74 68 ere must be eith
376b0 65 72 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 er a blob or tex
376c0 74 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 69 t value stored i
376d0 6e 0a 2a 2a 20 74 68 65 20 6e 6f 6d 69 6e 61 74 n.** the nominat
376e0 65 64 20 63 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66 ed column.)^ ^If
376f0 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69 73 20 the new row is
37700 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 6e 20 74 not present in t
37710 68 65 20 74 61 62 6c 65 2c 20 6f 72 20 69 66 0a he table, or if.
37720 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 63 ** it does not c
37730 6f 6e 74 61 69 6e 20 61 20 62 6c 6f 62 20 6f 72 ontain a blob or
37740 20 74 65 78 74 20 76 61 6c 75 65 2c 20 6f 72 20 text value, or
37750 69 66 20 61 6e 6f 74 68 65 72 20 65 72 72 6f 72 if another error
37760 20 6f 63 63 75 72 73 2c 20 61 6e 0a 2a 2a 20 53 occurs, an.** S
37770 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 QLite error code
37780 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
37790 20 74 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 the blob handle
377a0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 61 is considered a
377b0 62 6f 72 74 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20 borted..** ^All
377c0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
377d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
377e0 62 5f 72 65 61 64 28 29 5d 2c 20 5b 73 71 6c 69 b_read()], [sqli
377f0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
37800 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
37810 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28 29 5d 20 _blob_reopen()]
37820 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64 20 62 6c on an aborted bl
37830 6f 62 20 68 61 6e 64 6c 65 20 69 6d 6d 65 64 69 ob handle immedi
37840 61 74 65 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20 ately return.**
37850 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 20 5e 43 SQLITE_ABORT. ^C
37860 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
37870 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 6f 6e blob_bytes()] on
37880 20 61 6e 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 an aborted blob
37890 20 68 61 6e 64 6c 65 0a 2a 2a 20 61 6c 77 61 79 handle.** alway
378a0 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a s returns zero..
378b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
378c0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 tion sets the da
378d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 65 72 tabase handle er
378e0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
378f0 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sage..*/.SQLITE_
37900 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
37910 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 sqlite3_blob_re
37920 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f 62 6c 6f open(sqlite3_blo
37930 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 b *, sqlite3_int
37940 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 64);../*.** CAPI
37950 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 3REF: Close A BL
37960 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 OB Handle.**.**
37970 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 ^Closes an open
37980 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a [BLOB handle]..*
37990 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 *.** ^Closing a
379a0 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 BLOB shall cause
379b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 the current tra
379c0 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d nsaction to comm
379d0 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 it.** if there a
379e0 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 re no other BLOB
379f0 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 s, no pending pr
37a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37a10 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 s, and the.** da
37a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
37a30 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d n is in [autocom
37a40 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 mit mode]..** ^I
37a50 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 f any writes wer
37a60 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c e made to the BL
37a70 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 OB, they might b
37a80 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a e held in cache.
37a90 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f ** until the clo
37aa0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 se operation if
37ab0 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a they will fit..*
37ac0 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 *.** ^(Closing t
37ad0 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f he BLOB often fo
37ae0 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 rces the changes
37af0 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 .** out to disk
37b00 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f and so if any I/
37b10 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 O errors occur,
37b20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 they will likely
37b30 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 occur.** at the
37b40 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 time when the B
37b50 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 LOB is closed.
37b60 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 Any errors that
37b70 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 occur during.**
37b80 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f closing are repo
37b90 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 rted as a non-ze
37ba0 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e ro return value.
37bb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 )^.**.** ^(The B
37bc0 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e LOB is closed un
37bd0 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 conditionally.
37be0 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 Even if this rou
37bf0 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 tine returns.**
37c00 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 an error code, t
37c10 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c he BLOB is still
37c20 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a closed.)^.**.**
37c30 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 ^Calling this r
37c40 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 outine with a nu
37c50 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 ll pointer (such
37c60 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 as would be ret
37c70 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 urned.** by a fa
37c80 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 iled call to [sq
37c90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
37ca0 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 )]) is a harmles
37cb0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 s no-op..*/.int
37cc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
37cd0 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 se(sqlite3_blob
37ce0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
37cf0 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 REF: Return The
37d00 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 Size Of An Open
37d10 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 BLOB.**.** ^Retu
37d20 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 rns the size in
37d30 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f bytes of the BLO
37d40 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 B accessible via
37d50 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 the .** success
37d60 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c fully opened [BL
37d70 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 OB handle] in it
37d80 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e s only argument.
37d90 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d ^The.** increm
37da0 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 ental blob I/O r
37db0 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 outines can only
37dc0 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 read or overwri
37dd0 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a ting existing.**
37de0 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 blob content; t
37df0 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 hey cannot chang
37e00 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 e the size of a
37e10 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 blob..**.** This
37e20 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f routine only wo
37e30 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 rks on a [BLOB h
37e40 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 andle] which has
37e50 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a been created.**
37e60 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 by a prior succ
37e70 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
37e80 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
37e90 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 n()] and which h
37ea0 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 as not.** been c
37eb0 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 losed by [sqlite
37ec0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
37ed0 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 Passing any ot
37ee0 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a her pointer in.*
37ef0 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e * to this routin
37f00 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 e results in und
37f10 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
37f20 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 bly undesirable
37f30 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 behavior..*/.int
37f40 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 sqlite3_blob_by
37f50 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 tes(sqlite3_blob
37f60 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);../*.** CAPI
37f70 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 3REF: Read Data
37f80 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 From A BLOB Incr
37f90 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 ementally.**.**
37fa0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^(This function
37fb0 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 is used to read
37fc0 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 data from an ope
37fd0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 n [BLOB handle]
37fe0 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 into a.** caller
37ff0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 -supplied buffer
38000 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 . N bytes of dat
38010 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 a are copied int
38020 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 o buffer Z.** fr
38030 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 om the open BLOB
38040 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 , starting at of
38050 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a fset iOffset.)^.
38060 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 **.** ^If offset
38070 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
38080 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 than N bytes fr
38090 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
380a0 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 e BLOB,.** [SQLI
380b0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
380c0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
380d0 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 a is read. ^If
380e0 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a N or iOffset is.
380f0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ** less than zer
38100 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 o, [SQLITE_ERROR
38110 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
38120 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
38130 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 d..** ^The size
38140 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 of the blob (and
38150 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d hence the maxim
38160 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f um value of N+iO
38170 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 ffset).** can be
38180 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e determined usin
38190 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 g the [sqlite3_b
381a0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 lob_bytes()] int
381b0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 erface..**.** ^A
381c0 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 n attempt to rea
381d0 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 d from an expire
381e0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
381f0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
38200 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
38210 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a SQLITE_ABORT]..*
38220 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 *.** ^(On succes
38230 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f s, sqlite3_blob_
38240 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 read() returns S
38250 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 QLITE_OK..** Oth
38260 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f erwise, an [erro
38270 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
38280 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
38290 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
382a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f )^.**.** This ro
382b0 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 utine only works
382c0 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 on a [BLOB hand
382d0 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 le] which has be
382e0 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 en created.** by
382f0 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 a prior success
38300 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
38310 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
38320 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 ] and which has
38330 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 not.** been clos
38340 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
38350 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 lob_close()]. P
38360 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 assing any other
38370 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 pointer in.** t
38380 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 o this routine r
38390 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
383a0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
383b0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
383c0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 avior..**.** See
383d0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
383e0 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a blob_write()]..*
383f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
38400 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f ob_read(sqlite3_
38410 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c blob *, void *Z,
38420 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 int N, int iOff
38430 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
38440 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 I3REF: Write Dat
38450 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e a Into A BLOB In
38460 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a crementally.**.*
38470 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
38480 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 is used to writ
38490 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f e data into an o
384a0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 pen [BLOB handle
384b0 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c ] from a.** call
384c0 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 er-supplied buff
384d0 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 er. ^N bytes of
384e0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 data are copied
384f0 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 from the buffer
38500 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 Z.** into the op
38510 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e en BLOB, startin
38520 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 g at offset iOff
38530 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 set..**.** ^If t
38540 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
38550 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
38560 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 irst argument wa
38570 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 s not opened for
38580 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 .** writing (the
38590 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
385a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
385b0 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 b_open()] was ze
385c0 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e ro),.** this fun
385d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 ction returns [S
385e0 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e QLITE_READONLY].
385f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
38600 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d ction may only m
38610 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e odify the conten
38620 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 ts of the BLOB;
38630 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 it is.** not pos
38640 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 sible to increas
38650 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 e the size of a
38660 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 BLOB using this
38670 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 API..** ^If offs
38680 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 et iOffset is le
38690 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 ss than N bytes
386a0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 from the end of
386b0 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 the BLOB,.** [SQ
386c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 LITE_ERROR] is r
386d0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 eturned and no d
386e0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 ata is written.
386f0 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 ^If N is.** les
38700 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c s than zero [SQL
38710 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
38720 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
38730 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a ta is written..*
38740 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 * The size of th
38750 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 e BLOB (and henc
38760 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 e the maximum va
38770 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 lue of N+iOffset
38780 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 ).** can be dete
38790 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 rmined using the
387a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 [sqlite3_blob_b
387b0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 ytes()] interfac
387c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 e..**.** ^An att
387d0 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f empt to write to
387e0 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f an expired [BLO
387f0 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 B handle] fails
38800 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 with an.** error
38810 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
38820 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 _ABORT]. ^Write
38830 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 s to the BLOB th
38840 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 at occurred.** b
38850 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 efore the [BLOB
38860 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 handle] expired
38870 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 are not rolled b
38880 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 ack by the.** ex
38890 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 piration of the
388a0 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f handle, though o
388b0 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 f course those c
388c0 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 hanges might.**
388d0 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 have been overwr
388e0 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 itten by the sta
388f0 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 tement that expi
38900 72 65 64 20 74 68 65 20 42 4c 4f 42 20 6